Add FunctionCall.getNumRetries.

FunctionCall.getNumRetries returns the number of times the wrapped function was retried. This fixes #10.

Author: MathieuTurcotte

CHANGES.md

@@ -5,6 +5,8 @@
 - Replace `FunctionCall.getResults` by `FunctionCall.getLastResult` to avoid
   storing intermediary results forever as this may lead to memory exhaustion
   when used in conjunction with an infinite number of backoffs.
+- Add `FunctionCall.getNumRetries` which returns the number of times the
+  wrapped function was retried.
 
 ## 2.3.0
 

README.md

@@ -90,6 +90,8 @@ Typical usage looks like the following.
 
 ``` js
 var call = backoff.call(get, 'https://duplika.ca/', function(err, res) {
+    console.log('Num retries: ' + call.getNumRetries());
+
     if (err) {
         console.log('Error: ' + err.message);
     } else {
@@ -306,6 +308,13 @@ var results = call.getLastResult();
 var error = results[0];
 ```
 
+#### call.getNumRetries()
+
+Returns the number of times the wrapped function call was retried. For a
+wrapped function that succeeded immediately, this would return 0. This
+method can be called at any point in time during the call life cycle, i.e.
+before, during and after the wrapped function invocation.
+
 #### call.start()
 
 Initiates the call the wrapped function. This method should only be called

docs/function_call.html

@@ -104,6 +104,7 @@ <h1>function_call.js</h1>
     <span class="keyword">this</span>.arguments_ = args;
     <span class="keyword">this</span>.callback_ = callback;
     <span class="keyword">this</span>.lastResult_ = [];
+    <span class="keyword">this</span>.numRetries_ = <span class="number">0</span>;
 
     <span class="keyword">this</span>.backoff_ = <span class="literal">null</span>;
     <span class="keyword">this</span>.strategy_ = <span class="literal">null</span>;
@@ -305,6 +306,23 @@ <h1>function_call.js</h1>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-14">&#182;</a>
               </div>
+              <p>Returns the number of times the wrapped function call was retried.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>FunctionCall.prototype.getNumRetries = <span class="keyword">function</span>() {
+    <span class="keyword">return</span> <span class="keyword">this</span>.numRetries_;
+};</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-15">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-15">&#182;</a>
+              </div>
               <p>Sets the backoff limit.</p>
 
             </div>
@@ -318,11 +336,11 @@ <h1>function_call.js</h1>
         </li>
 
 
-        <li id="section-15">
+        <li id="section-16">
             <div class="annotation">
 
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-15">&#182;</a>
+                <a class="pilcrow" href="#section-16">&#182;</a>
               </div>
               <p>Aborts the call.</p>
 
@@ -341,11 +359,11 @@ <h1>function_call.js</h1>
         </li>
 
 
-        <li id="section-16">
+        <li id="section-17">
             <div class="annotation">
 
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-16">&#182;</a>
+                <a class="pilcrow" href="#section-17">&#182;</a>
               </div>
               <p>Initiates the call to the wrapped function. Accepts an optional factory
 function used to create the backoff instance; used when testing.</p>
@@ -362,7 +380,7 @@ <h1>function_call.js</h1>
         backoffFactory(strategy) :
         <span class="keyword">new</span> Backoff(strategy);
 
-    <span class="keyword">this</span>.backoff_.on(<span class="string">'ready'</span>, <span class="keyword">this</span>.doCall_.bind(<span class="keyword">this</span>));
+    <span class="keyword">this</span>.backoff_.on(<span class="string">'ready'</span>, <span class="keyword">this</span>.doCall_.bind(<span class="keyword">this</span>, <span class="literal">true</span> <span class="comment">/* isRetry */</span>));
     <span class="keyword">this</span>.backoff_.on(<span class="string">'fail'</span>, <span class="keyword">this</span>.doCallback_.bind(<span class="keyword">this</span>));
     <span class="keyword">this</span>.backoff_.on(<span class="string">'backoff'</span>, <span class="keyword">this</span>.handleBackoff_.bind(<span class="keyword">this</span>));
 
@@ -371,23 +389,26 @@ <h1>function_call.js</h1>
     }
 
     <span class="keyword">this</span>.state_ = FunctionCall.State_.RUNNING;
-    <span class="keyword">this</span>.doCall_();
+    <span class="keyword">this</span>.doCall_(<span class="literal">false</span> <span class="comment">/* isRetry */</span>);
 };</pre></div></div>
 
         </li>
 
 
-        <li id="section-17">
+        <li id="section-18">
             <div class="annotation">
 
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-17">&#182;</a>
+                <a class="pilcrow" href="#section-18">&#182;</a>
               </div>
               <p>Calls the wrapped function.</p>
 
             </div>
 
-            <div class="content"><div class='highlight'><pre>FunctionCall.prototype.doCall_ = <span class="keyword">function</span>() {
+            <div class="content"><div class='highlight'><pre>FunctionCall.prototype.doCall_ = <span class="keyword">function</span>(isRetry) {
+    <span class="keyword">if</span> (isRetry) {
+        <span class="keyword">this</span>.numRetries_++;
+    }
     <span class="keyword">var</span> eventArgs = [<span class="string">'call'</span>].concat(<span class="keyword">this</span>.arguments_);
     events.EventEmitter.prototype.emit.apply(<span class="keyword">this</span>, eventArgs);
     <span class="keyword">var</span> callback = <span class="keyword">this</span>.handleFunctionCallback_.bind(<span class="keyword">this</span>);
@@ -397,11 +418,11 @@ <h1>function_call.js</h1>
         </li>
 
 
-        <li id="section-18">
+        <li id="section-19">
             <div class="annotation">
 
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-18">&#182;</a>
+                <a class="pilcrow" href="#section-19">&#182;</a>
               </div>
               <p>Calls the wrapped function&#39;s callback with the last result returned by the
 wrapped function.</p>
@@ -415,11 +436,11 @@ <h1>function_call.js</h1>
         </li>
 
 
-        <li id="section-19">
+        <li id="section-20">
             <div class="annotation">
 
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-19">&#182;</a>
+                <a class="pilcrow" href="#section-20">&#182;</a>
               </div>
               <p>Handles wrapped function&#39;s completion. This method acts as a replacement
 for the original callback function.</p>
@@ -446,11 +467,11 @@ <h1>function_call.js</h1>
         </li>
 
 
-        <li id="section-20">
+        <li id="section-21">
             <div class="annotation">
 
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-20">&#182;</a>
+                <a class="pilcrow" href="#section-21">&#182;</a>
               </div>
               <p>Handles the backoff event by reemitting it.</p>
 

examples/function_call.js

@@ -27,7 +27,7 @@ function get(options, callback) {
 
 var call = backoff.call(get, URL, function(err, res) {
     // Notice how the call is captured inside the closure.
-    console.log('Last result: ' + util.inspect(call.getLastResult()));
+    console.log('Num retries: ' + call.getNumRetries());
 
     if (err) {
         console.log('Error: ' + err.message);

lib/function_call.js

@@ -20,6 +20,7 @@ function FunctionCall(fn, args, callback) {
     this.arguments_ = args;
     this.callback_ = callback;
     this.lastResult_ = [];
+    this.numRetries_ = 0;
 
     this.backoff_ = null;
     this.strategy_ = null;
@@ -76,6 +77,11 @@ FunctionCall.prototype.getLastResult = function() {
     return this.lastResult_.concat();
 };
 
+// Returns the number of times the wrapped function call was retried.
+FunctionCall.prototype.getNumRetries = function() {
+    return this.numRetries_;
+};
+
 // Sets the backoff limit.
 FunctionCall.prototype.failAfter = function(maxNumberOfRetry) {
     precond.checkState(this.isPending(), 'FunctionCall in progress.');
@@ -106,7 +112,7 @@ FunctionCall.prototype.start = function(backoffFactory) {
         backoffFactory(strategy) :
         new Backoff(strategy);
 
-    this.backoff_.on('ready', this.doCall_.bind(this));
+    this.backoff_.on('ready', this.doCall_.bind(this, true /* isRetry */));
     this.backoff_.on('fail', this.doCallback_.bind(this));
     this.backoff_.on('backoff', this.handleBackoff_.bind(this));
 
@@ -115,11 +121,14 @@ FunctionCall.prototype.start = function(backoffFactory) {
     }
 
     this.state_ = FunctionCall.State_.RUNNING;
-    this.doCall_();
+    this.doCall_(false /* isRetry */);
 };
 
 // Calls the wrapped function.
-FunctionCall.prototype.doCall_ = function() {
+FunctionCall.prototype.doCall_ = function(isRetry) {
+    if (isRetry) {
+        this.numRetries_++;
+    }
     var eventArgs = ['call'].concat(this.arguments_);
     events.EventEmitter.prototype.emit.apply(this, eventArgs);
     var callback = this.handleFunctionCallback_.bind(this);

tests/function_call.js

@@ -259,6 +259,27 @@ exports["FunctionCall"] = {
         test.done();
     },
 
+    "getNumRetries should return the number of retries": function(test) {
+        var call = new FunctionCall(this.wrappedFn, [], this.callback);
+
+        this.wrappedFn.yields(1);
+        call.start(this.backoffFactory);
+        // The inital call doesn't count as a retry.
+        test.equals(0, call.getNumRetries());
+
+        for (var i = 2; i < 5; i++) {
+            this.wrappedFn.yields(i);
+            this.backoff.emit('ready');
+            test.equals(i - 1, call.getNumRetries());
+        }
+
+        this.wrappedFn.yields(null);
+        this.backoff.emit('ready');
+        test.equals(4, call.getNumRetries());
+
+        test.done();
+    },
+
     "wrapped function's errors should be propagated": function(test) {
         var call = new FunctionCall(this.wrappedFn, [1, 2, 3], this.callback);
         this.wrappedFn.throws(new Error());