Expand api coverage

README.md

@@ -56,6 +56,11 @@ console.log(histogram.percentiles())
 
   * <a href="#histogram"><code>Histogram</code></a>
   * <a href="#record"><code>histogram#<b>record()</b></code></a>
+  * <a href="#recordCorrectedValue"><code>histogram#<b>recordCorrectedValue()</b></code></a>
+  * <a href="#add"><code>histogram#<b>add()</b></code></a>
+  * <a href="#subtract"><code>histogram#<b>subtract()</b></code></a>
+  * <a href="#copy"><code>histogram#<b>copy()</b></code></a>
+  * <a href="#equals"><code>histogram#<b>equals()</b></code></a>
   * <a href="#min"><code>histogram#<b>min()</b></code></a>
   * <a href="#max"><code>histogram#<b>max()</b></code></a>
   * <a href="#mean"><code>histogram#<b>mean()</b></code></a>
@@ -65,11 +70,34 @@ console.log(histogram.percentiles())
   * <a href="#encode"><code>histogram#<b>encode()</b></code></a>
   * <a href="#decode"><code>histogram#<b>decode()</b></code></a>
   * <a href="#reset"><code>histogram#<b>reset()</b></code></a>
-
+  * <a href="#countAtValue"><code>histogram#<b>countAtValue()</b></code></a>
+  * <a href="#countBetweenValues"><code>histogram#<b>countBetweenValues()</b></code></a>
+  * <a href="#lowestEquivalentValue"><code>histogram#<b>lowestEquivalentValue()</b></code></a>
+  * <a href="#medianEquivalentValue"><code>histogram#<b>medianEquivalentValue()</b></code></a>
+  * <a href="#highestEquivalentValue"><code>histogram#<b>highestEquivalentValue()</b></code></a>
+  * <a href="#nextNonEquivalentValue"><code>histogram#<b>nextNonEquivalentValue()</b></code></a>
+  * <a href="#valuesAreEquivalent"><code>histogram#<b>valuesAreEquivalent()</b></code></a>
+
+  #### Properties
+  * <a href="#lowestTrackableValue"><code>histogram#lowestTrackableValue</code></a>
+  * <a href="#highestTrackableValue"><code>histogram#highestTrackableValue</code></a>
+  * <a href="#significantFigures"><code>histogram#significantFigures</code></a>
+  * <a href="#totalCount"><code>histogram#totalCount</code></a>
+  * <a href="#memorySize"><code>histogram#memorySize</code></a>
+
+  ### Iteration
+  The module provides multiple means of <a href="#iteration">iterating</a> through the data
+  * <a href="#percentileValues"><code>histogram#percentileValues()</code></a>
+  * <a href="#linearValues"><code>histogram#linearValues()</code></a>
+  * <a href="#logarithmicValues"><code>histogram#logarithmicValues()</code></a>
+  * <a href="#recordedValues"><code>histogram#recordedValues()</code></a>
+  * <a href="#allValues"><code>histogram#allValues()</code></a>
+
+
 -------------------------------------------------------
 <a name="histogram"></a>
 
-### Histogram(lowest, max, figures)
+### new Histogram(lowest, max, figures)
 
 Create a new histogram with:
 
@@ -82,10 +110,60 @@ Create a new histogram with:
 -------------------------------------------------------
 <a name="record"></a>
 
-### histogram.record(value)
+### histogram.record(value[, count = 1])
 
-Record `value` in the histogram. Returns `true` if the recording was
+Record `value` in the histogram with a count of `count`. Returns `true` if the recording was
 successful, `false` otherwise.
+-------------------------------------------------------
+<a name="recordCorrectedValue"></a>
+
+### histogram.recordCorrectedValue(value, expectedInterval, count = 1)
+
+Record `value` in the histogram with a count of `count` and backfill based on a `expectedInterval`.
+This is specifically used for recording latency.  If `value` is larger than the `expectedInterval` 
+then the latency recording system has experienced co-ordinated omission.  This method fills in the
+values that would have occurred had the client providing the load not been blocked.
+
+Returns `true` if the recording was successful, `false` otherwise.
+
+-------------------------------------------------------
+<a name="add"></a>
+
+### histogram.add(other[, expectedIntervalBetweenValueSamples])
+
+Adds values from `other` to `this` histogram.  
+
+If `expectedIntervalBetweenValueSamples` is specified, values are 
+backfilled with values that would have occurred had the client providing the load 
+not been blocked. The values added will include an auto-generated additional series of
+decreasingly-smaller (down to the `expectedIntervalBetweenValueSamples`) value records for each count found
+in the current histogram that is larger than the `expectedIntervalBetweenValueSamples`.
+
+Returns the number of values dropped while copying. Values will be dropped
+if they are outside of `histogram.lowestTrackableValue` and  `histogram.highestTrackableValue`. 
+-------------------------------------------------------
+<a name="subtract"></a>
+
+### histogram.subtract(other)
+
+Subtract the contents of `other` from `this` histogram.  
+
+Returns the number of values dropped while subtracting. Values will be dropped
+if they would cause the count to fall below zero. 
+
+-------------------------------------------------------
+<a name="copy"></a>
+
+### histogram.copy()
+
+Create a copy of this histogram, complete with data and settings.
+
+-------------------------------------------------------
+<a name="equals"></a>
+
+### histogram.equals(other)
+
+Determine if this histogram is equivalent to another.
 
 -------------------------------------------------------
 <a name="min"></a>
@@ -164,6 +242,177 @@ Reads a `Buffer` and deserialize an histogram.
 
 Resets the histogram so it can be reused.
 
+-------------------------------------------------------
+<a name="countAtValue"></a>
+
+### histogram.countAtValue(value)
+
+Get the count of recorded values at a specific value (to within the histogram resolution at the value level).
+
+-------------------------------------------------------
+<a name="countBetweenValues​"></a>
+
+### histogram.countBetweenValues​(lowValue, highValue)
+
+Get the count of recorded values within a range of value levels (inclusive to within the histogram's resolution).
+
+##### Parameters
+* `lowValue` - The lower value bound on the range for which to provide the recorded count. Will be rounded down with lowestEquivalentValue.
+* `highValue` - The higher value bound on the range for which to provide the recorded count. Will be rounded up with highestEquivalentValue.
+
+-------------------------------------------------------
+<a name="lowestEquivalentValue"></a>
+
+### histogram.lowestEquivalentValue(value)
+
+Get the lowest value that is equivalent to the given value within the 
+histogram's resolution, where "equivalent" means that value samples 
+recorded for any two equivalent values are counted in a common total count.
+
+-------------------------------------------------------
+<a name="medianEquivalentValue"></a>
+
+### histogram.medianEquivalentValue(value)
+
+Get a value that lies in the middle (rounded up) of the range of values equivalent to the given value,
+where "equivalent" means that value samples recorded for any two equivalent values are counted in a 
+common total count.
+
+------------------------------------------------------
+<a name="highestEquivalentValue"></a>
+
+### histogram.highestEquivalentValue(value)
+
+Get the highest value that is equivalent to the given value within the 
+histogram's resolution, where "equivalent" means that value samples 
+recorded for any two equivalent values are counted in a common total count.
+
+------------------------------------------------------
+<a name="nextNonEquivalentValue"></a>
+
+### histogram.nextNonEquivalentValue(value)
+
+Get the next value that is not equivalent to the given value within the histogram's resolution.
+
+------------------------------------------------------
+<a name="valuesAreEquivalent"></a>
+
+### histogram.valuesAreEquivalent(value1, value2)
+
+Determine if two values are equivalent within the histogram's resolution
+where "equivalent" means that value samples recorded for any two
+equivalent values are counted in a common total count.
+-------------------------------------------------------
+<a name="properties"></a>
+## Properties
+
+<a name="lowestTrackableValue"></a>
+### histogram.lowestTrackableValue
+
+Get the configured lowestTrackableValue
+
+-------------------------------------------------------
+<a name="highestTrackableValue"></a>
+### histogram.highestTrackableValue
+
+Get the configured highestTrackableValue
+
+-------------------------------------------------------
+<a name="significantFigures"></a>
+### histogram.significantFigures
+
+Get the configured number of significant value digits
+
+-------------------------------------------------------
+<a name="totalCount"></a>
+### histogram.totalCount
+
+Gets the total number of recorded values.
+
+-------------------------------------------------------
+<a name="memorySize"></a>
+### histogram.memorySize
+
+Get the memory size of the Histogram.
+
+-------------------------------------------------------
+##Iteration
+<a name="iteration"></a>
+
+Histograms supports multiple convenient forms of iterating through the
+histogram data set, including linear, logarithmic, and percentile iteration
+mechanisms, as well as means for iterating through each recorded value or
+each possible value level. The iteration mechanisms are accessible through
+the through the following Histogram methods:
+
+<a name="percentileValues"></a>
+ - `histogram.percentileValues(ticksPerHalfDistance)`: <br/>  Used for iterating through histogram values according to percentile levels.
+ The iteration is performed in steps that start at 0% and reduce their distance to 100% according to the
+ <i>ticksPerHalfDistance</i> parameter, ultimately reaching 100% when all recorded histogram
+ values are exhausted.
+
+ <a name="linearValues"></a>
+ - `histogram.linearValues(valueUnitsPerBucket)`: <br/> Used for iterating through histogram values in linear steps. The iteration is performed 
+ in steps of valueUnitsPerBucket in size, terminating when all recorded histogram values are exhausted. Note that each 
+ iteration "bucket" includes values up to and including the next bucket boundary value.
+
+ <a name="logarithmicValues"></a>
+ - `histogram.logarithmicValues(valueUnitsInFirstBucket, logBase)`:  <br/> Iterates through histogram values in logarithmically 
+ increasing levels. The iteration is performed in steps that start at `valueUnitsInFirstBucket` and increase exponentially 
+ according to `logBase`, terminating when all recorded histogram values are exhausted. Note that each iteration "bucket" 
+ includes values up to and including the next bucket boundary value.
+
+ <a name="recordedValues"></a>
+ - `histogram.recordedValues()`:  <br/> An iterator that enumerate over all non-zero values.
+
+  <a name="allValues"></a>
+ - `histogram.allValues()`:  <br/>
+ Iterates through histogram values using the finest granularity steps supported by the underlying representation.
+
+The iterator methods support the `es6` iterator protocol, so enumeration is typically done with a for-of loop statement. E.g.:
+
+``` javascript
+ for (let v of histogram.percentileValues(ticksPerHalfDistance)) {
+     ...
+ }
+```
+
+ or
+
+``` javascript
+ for (let v of histogram.linearBucketValues(unitsPerBucket)) {
+     ...
+ }
+```
+
+
+The loop iteration value is an `object` with the following fields in the general case: 
+ * <b><code>value</code></b> : The actual value level that was iterated to by the iterator
+ * <b><code>valueIteratedTo</code></b> : The actual value level that was iterated to by the iterator
+ * <b><code>valueIteratedFrom</code></b> : The actual value level that was iterated from by the iterator
+ * <b><code>count</code></b> : The count of recorded values in the histogram that
+ exactly match this [`lowestEquivalentValue(valueIteratedTo)`...`highestEquivalentValue(valueIteratedTo)`] value range.
+ * <b><code>countAddedThisIteration</code></b> : The count of recorded values that
+    were added as a result on this iteration step. Since multiple iteration
+    steps may occur with overlapping equivalent value ranges, the count may be lower than the count found at
+    the value (e.g. multiple linear steps or percentile levels can occur within a single equivalent value range)
+ * <b><code>lowestEquivalentValue</code></b> : The lowest value that is equivalent to the current iteration 
+ value within the histogram's resolution.
+ * <b><code>medianEquivalentValue</code></b> : The lowest value that is equivalent to the current iteration 
+  value within the histogram's resolution.
+ * <b><code>highestEquivalentValue</code> : The highest value that is equivalent to the current iteration 
+  value within the histogram's resolution.
+ * <b><code>medianEquivalentValue</code></b> : a value that lies in the middle (rounded up) of the range of values 
+ (`lowestEquivalentValue` ... `highestEquivalentValue`). "Equivalent" means that value samples recorded for any two equivalent values are counted in a common total count.
+
+ In addition to the above, the `percentileValues` iterator returns the following fields:
+ * <b><code>cumulativeCount</code></b> : The total count of all recorded values in the histogram at values 
+    equal or smaller than `valueIteratedTo`.
+ * <b><code>percentile</code></b> : The percentile of recorded values in the histogram at values equal or smaller 
+ than `valueIteratedTo`.
+
+
+
 ## Acknowledgements
 
 This project was kindly sponsored by [nearForm](http://nearform.com).

binding.gyp

@@ -2,6 +2,24 @@
   "targets": [
     {
       "target_name": "<(module_name)",
+      'cflags!': [ '-fno-exceptions' ],
+      'cflags_cc!': [ '-fno-exceptions' ],
+      'conditions': [
+        ['OS=="win"', {
+          "msvs_settings": {
+            "VCCLCompilerTool": {
+              "ExceptionHandling": 1
+            }
+          }
+        }],
+        ['OS=="mac"', {
+          "xcode_settings": {
+            "CLANG_CXX_LIBRARY": "libc++",
+            'GCC_ENABLE_CPP_EXCEPTIONS': 'YES',
+            'MACOSX_DEPLOYMENT_TARGET': '10.7'
+          }
+        }]
+      ],
       "sources": [
         "src/hdr_encoding.h",
         "src/hdr_encoding.c",
@@ -11,14 +29,18 @@
         "src/hdr_histogram_log.c",
         "src/hdr_time.h",
         "src/hdr_time.c",
+        "hdr_histogram_ex.h",
+        "hdr_histogram_ex.c",
         "hdr_histogram_wrap.cc",
+        "hdr_histogram_iterator_wrap.cc",
         "histogram.cc"
       ],
+      'defines': [ 'NAPI_CPP_EXCEPTIONS' ], 
       "dependencies": [
         "<(module_root_dir)/zlib/zlib.gyp:zlib"
       ],
       "include_dirs": [
-        "<!(node -e \"require('nan')\")",
+        "<!@(node -p \"require('node-addon-api').include\")",
         "src/"
       ]
     },