Debian Codegraph @

docs/function_call.html

raw
1 <!DOCTYPE html>
2
3 <html>
4 <head>
5 <title>function_call.js</title>
6 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
7 <meta name="viewport" content="width=device-width, target-densitydpi=160dpi, initial-scale=1.0; maximum-scale=1.0; user-scalable=0;">
8 <link rel="stylesheet" media="all" href="docco.css" />
9 </head>
10 <body>
11 <div id="container">
12 <div id="background"></div>
13
14 <ul id="jump_to">
15 <li>
16 <a class="large" href="javascript:void(0);">Jump To &hellip;</a>
17 <a class="small" href="javascript:void(0);">+</a>
18 <div id="jump_wrapper">
19 <div id="jump_page">
20
21
22 <a class="source" href="index.html">
23 index.js
24 </a>
25
26
27 <a class="source" href="backoff.html">
28 backoff.js
29 </a>
30
31
32 <a class="source" href="function_call.html">
33 function_call.js
34 </a>
35
36
37 <a class="source" href="exponential.html">
38 exponential.js
39 </a>
40
41
42 <a class="source" href="fibonacci.html">
43 fibonacci.js
44 </a>
45
46
47 <a class="source" href="strategy.html">
48 strategy.js
49 </a>
50
51 </div>
52 </li>
53 </ul>
54
55 <ul class="sections">
56
57 <li id="title">
58 <div class="annotation">
59 <h1>function_call.js</h1>
60 </div>
61 </li>
62
63
64
65 <li id="section-1">
66 <div class="annotation">
67
68 <div class="pilwrap ">
69 <a class="pilcrow" href="#section-1">&#182;</a>
70 </div>
71 <pre><code> Copyright (c) <span class="hljs-number">2012</span> Mathieu Turcotte
72 Licensed under the MIT license.
73 </code></pre>
74 </div>
75
76 <div class="content"><div class='highlight'><pre>
77 <span class="hljs-keyword">var</span> events = <span class="hljs-built_in">require</span>(<span class="hljs-string">'events'</span>);
78 <span class="hljs-keyword">var</span> precond = <span class="hljs-built_in">require</span>(<span class="hljs-string">'precond'</span>);
79 <span class="hljs-keyword">var</span> util = <span class="hljs-built_in">require</span>(<span class="hljs-string">'util'</span>);
80
81 <span class="hljs-keyword">var</span> Backoff = <span class="hljs-built_in">require</span>(<span class="hljs-string">'./backoff'</span>);
82 <span class="hljs-keyword">var</span> FibonacciBackoffStrategy = <span class="hljs-built_in">require</span>(<span class="hljs-string">'./strategy/fibonacci'</span>);</pre></div></div>
83
84 </li>
85
86
87 <li id="section-2">
88 <div class="annotation">
89
90 <div class="pilwrap ">
91 <a class="pilcrow" href="#section-2">&#182;</a>
92 </div>
93 <p>Wraps a function to be called in a backoff loop.</p>
94
95 </div>
96
97 <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">FunctionCall</span><span class="hljs-params">(fn, args, callback)</span> {</span>
98 events.EventEmitter.call(<span class="hljs-keyword">this</span>);
99
100 precond.checkIsFunction(fn, <span class="hljs-string">'Expected fn to be a function.'</span>);
101 precond.checkIsArray(args, <span class="hljs-string">'Expected args to be an array.'</span>);
102 precond.checkIsFunction(callback, <span class="hljs-string">'Expected callback to be a function.'</span>);
103
104 <span class="hljs-keyword">this</span>.function_ = fn;
105 <span class="hljs-keyword">this</span>.arguments_ = args;
106 <span class="hljs-keyword">this</span>.callback_ = callback;
107 <span class="hljs-keyword">this</span>.lastResult_ = [];
108 <span class="hljs-keyword">this</span>.numRetries_ = <span class="hljs-number">0</span>;
109
110 <span class="hljs-keyword">this</span>.backoff_ = <span class="hljs-literal">null</span>;
111 <span class="hljs-keyword">this</span>.strategy_ = <span class="hljs-literal">null</span>;
112 <span class="hljs-keyword">this</span>.failAfter_ = -<span class="hljs-number">1</span>;
113
114 <span class="hljs-keyword">this</span>.state_ = FunctionCall.State_.PENDING;
115 }
116 util.inherits(FunctionCall, events.EventEmitter);</pre></div></div>
117
118 </li>
119
120
121 <li id="section-3">
122 <div class="annotation">
123
124 <div class="pilwrap ">
125 <a class="pilcrow" href="#section-3">&#182;</a>
126 </div>
127 <p>States in which the call can be.</p>
128
129 </div>
130
131 <div class="content"><div class='highlight'><pre>FunctionCall.State_ = {</pre></div></div>
132
133 </li>
134
135
136 <li id="section-4">
137 <div class="annotation">
138
139 <div class="pilwrap ">
140 <a class="pilcrow" href="#section-4">&#182;</a>
141 </div>
142 <p>Call isn’t started yet.</p>
143
144 </div>
145
146 <div class="content"><div class='highlight'><pre> PENDING: <span class="hljs-number">0</span>,</pre></div></div>
147
148 </li>
149
150
151 <li id="section-5">
152 <div class="annotation">
153
154 <div class="pilwrap ">
155 <a class="pilcrow" href="#section-5">&#182;</a>
156 </div>
157 <p>Call is in progress.</p>
158
159 </div>
160
161 <div class="content"><div class='highlight'><pre> RUNNING: <span class="hljs-number">1</span>,</pre></div></div>
162
163 </li>
164
165
166 <li id="section-6">
167 <div class="annotation">
168
169 <div class="pilwrap ">
170 <a class="pilcrow" href="#section-6">&#182;</a>
171 </div>
172 <p>Call completed successfully which means that either the wrapped function
173 returned successfully or the maximal number of backoffs was reached.</p>
174
175 </div>
176
177 <div class="content"><div class='highlight'><pre> COMPLETED: <span class="hljs-number">2</span>,</pre></div></div>
178
179 </li>
180
181
182 <li id="section-7">
183 <div class="annotation">
184
185 <div class="pilwrap ">
186 <a class="pilcrow" href="#section-7">&#182;</a>
187 </div>
188 <p>The call was aborted.</p>
189
190 </div>
191
192 <div class="content"><div class='highlight'><pre> ABORTED: <span class="hljs-number">3</span>
193 };</pre></div></div>
194
195 </li>
196
197
198 <li id="section-8">
199 <div class="annotation">
200
201 <div class="pilwrap ">
202 <a class="pilcrow" href="#section-8">&#182;</a>
203 </div>
204 <p>Checks whether the call is pending.</p>
205
206 </div>
207
208 <div class="content"><div class='highlight'><pre>FunctionCall.prototype.isPending = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> {</span>
209 <span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>.state_ == FunctionCall.State_.PENDING;
210 };</pre></div></div>
211
212 </li>
213
214
215 <li id="section-9">
216 <div class="annotation">
217
218 <div class="pilwrap ">
219 <a class="pilcrow" href="#section-9">&#182;</a>
220 </div>
221 <p>Checks whether the call is in progress.</p>
222
223 </div>
224
225 <div class="content"><div class='highlight'><pre>FunctionCall.prototype.isRunning = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> {</span>
226 <span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>.state_ == FunctionCall.State_.RUNNING;
227 };</pre></div></div>
228
229 </li>
230
231
232 <li id="section-10">
233 <div class="annotation">
234
235 <div class="pilwrap ">
236 <a class="pilcrow" href="#section-10">&#182;</a>
237 </div>
238 <p>Checks whether the call is completed.</p>
239
240 </div>
241
242 <div class="content"><div class='highlight'><pre>FunctionCall.prototype.isCompleted = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> {</span>
243 <span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>.state_ == FunctionCall.State_.COMPLETED;
244 };</pre></div></div>
245
246 </li>
247
248
249 <li id="section-11">
250 <div class="annotation">
251
252 <div class="pilwrap ">
253 <a class="pilcrow" href="#section-11">&#182;</a>
254 </div>
255 <p>Checks whether the call is aborted.</p>
256
257 </div>
258
259 <div class="content"><div class='highlight'><pre>FunctionCall.prototype.isAborted = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> {</span>
260 <span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>.state_ == FunctionCall.State_.ABORTED;
261 };</pre></div></div>
262
263 </li>
264
265
266 <li id="section-12">
267 <div class="annotation">
268
269 <div class="pilwrap ">
270 <a class="pilcrow" href="#section-12">&#182;</a>
271 </div>
272 <p>Sets the backoff strategy to use. Can only be called before the call is
273 started otherwise an exception will be thrown.</p>
274
275 </div>
276
277 <div class="content"><div class='highlight'><pre>FunctionCall.prototype.setStrategy = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(strategy)</span> {</span>
278 precond.checkState(<span class="hljs-keyword">this</span>.isPending(), <span class="hljs-string">'FunctionCall in progress.'</span>);
279 <span class="hljs-keyword">this</span>.strategy_ = strategy;
280 <span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>; <span class="hljs-comment">// Return this for chaining.</span>
281 };</pre></div></div>
282
283 </li>
284
285
286 <li id="section-13">
287 <div class="annotation">
288
289 <div class="pilwrap ">
290 <a class="pilcrow" href="#section-13">&#182;</a>
291 </div>
292 <p>Returns all intermediary results returned by the wrapped function since
293 the initial call.</p>
294
295 </div>
296
297 <div class="content"><div class='highlight'><pre>FunctionCall.prototype.getLastResult = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> {</span>
298 <span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>.lastResult_.concat();
299 };</pre></div></div>
300
301 </li>
302
303
304 <li id="section-14">
305 <div class="annotation">
306
307 <div class="pilwrap ">
308 <a class="pilcrow" href="#section-14">&#182;</a>
309 </div>
310 <p>Returns the number of times the wrapped function call was retried.</p>
311
312 </div>
313
314 <div class="content"><div class='highlight'><pre>FunctionCall.prototype.getNumRetries = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> {</span>
315 <span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>.numRetries_;
316 };</pre></div></div>
317
318 </li>
319
320
321 <li id="section-15">
322 <div class="annotation">
323
324 <div class="pilwrap ">
325 <a class="pilcrow" href="#section-15">&#182;</a>
326 </div>
327 <p>Sets the backoff limit.</p>
328
329 </div>
330
331 <div class="content"><div class='highlight'><pre>FunctionCall.prototype.failAfter = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(maxNumberOfRetry)</span> {</span>
332 precond.checkState(<span class="hljs-keyword">this</span>.isPending(), <span class="hljs-string">'FunctionCall in progress.'</span>);
333 <span class="hljs-keyword">this</span>.failAfter_ = maxNumberOfRetry;
334 <span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>; <span class="hljs-comment">// Return this for chaining.</span>
335 };</pre></div></div>
336
337 </li>
338
339
340 <li id="section-16">
341 <div class="annotation">
342
343 <div class="pilwrap ">
344 <a class="pilcrow" href="#section-16">&#182;</a>
345 </div>
346 <p>Aborts the call.</p>
347
348 </div>
349
350 <div class="content"><div class='highlight'><pre>FunctionCall.prototype.abort = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> {</span>
351 precond.checkState(!<span class="hljs-keyword">this</span>.isCompleted(), <span class="hljs-string">'FunctionCall already completed.'</span>);
352
353 <span class="hljs-keyword">if</span> (<span class="hljs-keyword">this</span>.isRunning()) {
354 <span class="hljs-keyword">this</span>.backoff_.reset();
355 }
356
357 <span class="hljs-keyword">this</span>.state_ = FunctionCall.State_.ABORTED;
358 };</pre></div></div>
359
360 </li>
361
362
363 <li id="section-17">
364 <div class="annotation">
365
366 <div class="pilwrap ">
367 <a class="pilcrow" href="#section-17">&#182;</a>
368 </div>
369 <p>Initiates the call to the wrapped function. Accepts an optional factory
370 function used to create the backoff instance; used when testing.</p>
371
372 </div>
373
374 <div class="content"><div class='highlight'><pre>FunctionCall.prototype.start = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(backoffFactory)</span> {</span>
375 precond.checkState(!<span class="hljs-keyword">this</span>.isAborted(), <span class="hljs-string">'FunctionCall aborted.'</span>);
376 precond.checkState(<span class="hljs-keyword">this</span>.isPending(), <span class="hljs-string">'FunctionCall already started.'</span>);
377
378 <span class="hljs-keyword">var</span> strategy = <span class="hljs-keyword">this</span>.strategy_ || <span class="hljs-keyword">new</span> FibonacciBackoffStrategy();
379
380 <span class="hljs-keyword">this</span>.backoff_ = backoffFactory ?
381 backoffFactory(strategy) :
382 <span class="hljs-keyword">new</span> Backoff(strategy);
383
384 <span class="hljs-keyword">this</span>.backoff_.on(<span class="hljs-string">'ready'</span>, <span class="hljs-keyword">this</span>.doCall_.bind(<span class="hljs-keyword">this</span>, <span class="hljs-literal">true</span> <span class="hljs-comment">/* isRetry */</span>));
385 <span class="hljs-keyword">this</span>.backoff_.on(<span class="hljs-string">'fail'</span>, <span class="hljs-keyword">this</span>.doCallback_.bind(<span class="hljs-keyword">this</span>));
386 <span class="hljs-keyword">this</span>.backoff_.on(<span class="hljs-string">'backoff'</span>, <span class="hljs-keyword">this</span>.handleBackoff_.bind(<span class="hljs-keyword">this</span>));
387
388 <span class="hljs-keyword">if</span> (<span class="hljs-keyword">this</span>.failAfter_ &gt; <span class="hljs-number">0</span>) {
389 <span class="hljs-keyword">this</span>.backoff_.failAfter(<span class="hljs-keyword">this</span>.failAfter_);
390 }
391
392 <span class="hljs-keyword">this</span>.state_ = FunctionCall.State_.RUNNING;
393 <span class="hljs-keyword">this</span>.doCall_(<span class="hljs-literal">false</span> <span class="hljs-comment">/* isRetry */</span>);
394 };</pre></div></div>
395
396 </li>
397
398
399 <li id="section-18">
400 <div class="annotation">
401
402 <div class="pilwrap ">
403 <a class="pilcrow" href="#section-18">&#182;</a>
404 </div>
405 <p>Calls the wrapped function.</p>
406
407 </div>
408
409 <div class="content"><div class='highlight'><pre>FunctionCall.prototype.doCall_ = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(isRetry)</span> {</span>
410 <span class="hljs-keyword">if</span> (isRetry) {
411 <span class="hljs-keyword">this</span>.numRetries_++;
412 }
413 <span class="hljs-keyword">var</span> eventArgs = [<span class="hljs-string">'call'</span>].concat(<span class="hljs-keyword">this</span>.arguments_);
414 events.EventEmitter.prototype.emit.apply(<span class="hljs-keyword">this</span>, eventArgs);
415 <span class="hljs-keyword">var</span> callback = <span class="hljs-keyword">this</span>.handleFunctionCallback_.bind(<span class="hljs-keyword">this</span>);
416 <span class="hljs-keyword">this</span>.function_.apply(<span class="hljs-literal">null</span>, <span class="hljs-keyword">this</span>.arguments_.concat(callback));
417 };</pre></div></div>
418
419 </li>
420
421
422 <li id="section-19">
423 <div class="annotation">
424
425 <div class="pilwrap ">
426 <a class="pilcrow" href="#section-19">&#182;</a>
427 </div>
428 <p>Calls the wrapped function’s callback with the last result returned by the
429 wrapped function.</p>
430
431 </div>
432
433 <div class="content"><div class='highlight'><pre>FunctionCall.prototype.doCallback_ = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> {</span>
434 <span class="hljs-keyword">this</span>.callback_.apply(<span class="hljs-literal">null</span>, <span class="hljs-keyword">this</span>.lastResult_);
435 };</pre></div></div>
436
437 </li>
438
439
440 <li id="section-20">
441 <div class="annotation">
442
443 <div class="pilwrap ">
444 <a class="pilcrow" href="#section-20">&#182;</a>
445 </div>
446 <p>Handles wrapped function’s completion. This method acts as a replacement
447 for the original callback function.</p>
448
449 </div>
450
451 <div class="content"><div class='highlight'><pre>FunctionCall.prototype.handleFunctionCallback_ = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> {</span>
452 <span class="hljs-keyword">if</span> (<span class="hljs-keyword">this</span>.isAborted()) {
453 <span class="hljs-keyword">return</span>;
454 }
455
456 <span class="hljs-keyword">var</span> args = <span class="hljs-built_in">Array</span>.prototype.slice.call(<span class="hljs-built_in">arguments</span>);
457 <span class="hljs-keyword">this</span>.lastResult_ = args; <span class="hljs-comment">// Save last callback arguments.</span>
458 events.EventEmitter.prototype.emit.apply(<span class="hljs-keyword">this</span>, [<span class="hljs-string">'callback'</span>].concat(args));
459
460 <span class="hljs-keyword">if</span> (args[<span class="hljs-number">0</span>]) {
461 <span class="hljs-keyword">this</span>.backoff_.backoff(args[<span class="hljs-number">0</span>]);
462 } <span class="hljs-keyword">else</span> {
463 <span class="hljs-keyword">this</span>.state_ = FunctionCall.State_.COMPLETED;
464 <span class="hljs-keyword">this</span>.doCallback_();
465 }
466 };</pre></div></div>
467
468 </li>
469
470
471 <li id="section-21">
472 <div class="annotation">
473
474 <div class="pilwrap ">
475 <a class="pilcrow" href="#section-21">&#182;</a>
476 </div>
477 <p>Handles the backoff event by reemitting it.</p>
478
479 </div>
480
481 <div class="content"><div class='highlight'><pre>FunctionCall.prototype.handleBackoff_ = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(number, delay, err)</span> {</span>
482 <span class="hljs-keyword">this</span>.emit(<span class="hljs-string">'backoff'</span>, number, delay, err);
483 };
484
485 module.exports = FunctionCall;</pre></div></div>
486
487 </li>
488
489 </ul>
490 </div>
491 </body>
492 </html>