vnfmarket/src/main/webapp/vnfmarket/node_modules/async/README.md

   1 # Async.js
   2
   3 Async is a utility module which provides straight-forward, powerful functions
   4 for working with asynchronous JavaScript. Although originally designed for
   5 use with [node.js](http://nodejs.org), it can also be used directly in the
   6 browser. Also supports [component](https://github.com/component/component).
   7
   8 Async provides around 20 functions that include the usual 'functional'
   9 suspects (map, reduce, filter, each…) as well as some common patterns
  10 for asynchronous control flow (parallel, series, waterfall…). All these
  11 functions assume you follow the node.js convention of providing a single
  12 callback as the last argument of your async function.
  13
  14
  15 ## Quick Examples
  16
  17 ```javascript
  18 async.map(['file1','file2','file3'], fs.stat, function(err, results){
  19     // results is now an array of stats for each file
  20 });
  21
  22 async.filter(['file1','file2','file3'], fs.exists, function(results){
  23     // results now equals an array of the existing files
  24 });
  25
  26 async.parallel([
  27     function(){ ... },
  28     function(){ ... }
  29 ], callback);
  30
  31 async.series([
  32     function(){ ... },
  33     function(){ ... }
  34 ]);
  35 ```
  36
  37 There are many more functions available so take a look at the docs below for a
  38 full list. This module aims to be comprehensive, so if you feel anything is
  39 missing please create a GitHub issue for it.
  40
  41 ## Common Pitfalls
  42
  43 ### Binding a context to an iterator
  44
  45 This section is really about bind, not about async. If you are wondering how to
  46 make async execute your iterators in a given context, or are confused as to why
  47 a method of another library isn't working as an iterator, study this example:
  48
  49 ```js
  50 // Here is a simple object with an (unnecessarily roundabout) squaring method
  51 var AsyncSquaringLibrary = {
  52   squareExponent: 2,
  53   square: function(number, callback){
  54     var result = Math.pow(number, this.squareExponent);
  55     setTimeout(function(){
  56       callback(null, result);
  57     }, 200);
  58   }
  59 };
  60
  61 async.map([1, 2, 3], AsyncSquaringLibrary.square, function(err, result){
  62   // result is [NaN, NaN, NaN]
  63   // This fails because the `this.squareExponent` expression in the square
  64   // function is not evaluated in the context of AsyncSquaringLibrary, and is
  65   // therefore undefined.
  66 });
  67
  68 async.map([1, 2, 3], AsyncSquaringLibrary.square.bind(AsyncSquaringLibrary), function(err, result){
  69   // result is [1, 4, 9]
  70   // With the help of bind we can attach a context to the iterator before
  71   // passing it to async. Now the square function will be executed in its
  72   // 'home' AsyncSquaringLibrary context and the value of `this.squareExponent`
  73   // will be as expected.
  74 });
  75 ```
  76
  77 ## Download
  78
  79 The source is available for download from
  80 [GitHub](http://github.com/caolan/async).
  81 Alternatively, you can install using Node Package Manager (npm):
  82
  83     npm install async
  84
  85 __Development:__ [async.js](https://github.com/caolan/async/raw/master/lib/async.js) - 29.6kb Uncompressed
  86
  87 ## In the Browser
  88
  89 So far it's been tested in IE6, IE7, IE8, FF3.6 and Chrome 5. Usage:
  90
  91 ```html
  92 <script type="text/javascript" src="async.js"></script>
  93 <script type="text/javascript">
  94
  95     async.map(data, asyncProcess, function(err, results){
  96         alert(results);
  97     });
  98
  99 </script>
 100 ```
 101
 102 ## Documentation
 103
 104 ### Collections
 105
 106 * [each](#each)
 107 * [eachSeries](#eachSeries)
 108 * [eachLimit](#eachLimit)
 109 * [map](#map)
 110 * [mapSeries](#mapSeries)
 111 * [mapLimit](#mapLimit)
 112 * [filter](#filter)
 113 * [filterSeries](#filterSeries)
 114 * [reject](#reject)
 115 * [rejectSeries](#rejectSeries)
 116 * [reduce](#reduce)
 117 * [reduceRight](#reduceRight)
 118 * [detect](#detect)
 119 * [detectSeries](#detectSeries)
 120 * [sortBy](#sortBy)
 121 * [some](#some)
 122 * [every](#every)
 123 * [concat](#concat)
 124 * [concatSeries](#concatSeries)
 125
 126 ### Control Flow
 127
 128 * [series](#series)
 129 * [parallel](#parallel)
 130 * [parallelLimit](#parallellimittasks-limit-callback)
 131 * [whilst](#whilst)
 132 * [doWhilst](#doWhilst)
 133 * [until](#until)
 134 * [doUntil](#doUntil)
 135 * [forever](#forever)
 136 * [waterfall](#waterfall)
 137 * [compose](#compose)
 138 * [applyEach](#applyEach)
 139 * [applyEachSeries](#applyEachSeries)
 140 * [queue](#queue)
 141 * [cargo](#cargo)
 142 * [auto](#auto)
 143 * [iterator](#iterator)
 144 * [apply](#apply)
 145 * [nextTick](#nextTick)
 146 * [times](#times)
 147 * [timesSeries](#timesSeries)
 148
 149 ### Utils
 150
 151 * [memoize](#memoize)
 152 * [unmemoize](#unmemoize)
 153 * [log](#log)
 154 * [dir](#dir)
 155 * [noConflict](#noConflict)
 156
 157
 158 ## Collections
 159
 160 <a name="forEach" />
 161 <a name="each" />
 162 ### each(arr, iterator, callback)
 163
 164 Applies an iterator function to each item in an array, in parallel.
 165 The iterator is called with an item from the list and a callback for when it
 166 has finished. If the iterator passes an error to this callback, the main
 167 callback for the each function is immediately called with the error.
 168
 169 Note, that since this function applies the iterator to each item in parallel
 170 there is no guarantee that the iterator functions will complete in order.
 171
 172 __Arguments__
 173
 174 * arr - An array to iterate over.
 175 * iterator(item, callback) - A function to apply to each item in the array.
 176   The iterator is passed a callback(err) which must be called once it has
 177   completed. If no error has occured, the callback should be run without
 178   arguments or with an explicit null argument.
 179 * callback(err) - A callback which is called after all the iterator functions
 180   have finished, or an error has occurred.
 181
 182 __Example__
 183
 184 ```js
 185 // assuming openFiles is an array of file names and saveFile is a function
 186 // to save the modified contents of that file:
 187
 188 async.each(openFiles, saveFile, function(err){
 189     // if any of the saves produced an error, err would equal that error
 190 });
 191 ```
 192
 193 ---------------------------------------
 194
 195 <a name="forEachSeries" />
 196 <a name="eachSeries" />
 197 ### eachSeries(arr, iterator, callback)
 198
 199 The same as each only the iterator is applied to each item in the array in
 200 series. The next iterator is only called once the current one has completed
 201 processing. This means the iterator functions will complete in order.
 202
 203
 204 ---------------------------------------
 205
 206 <a name="forEachLimit" />
 207 <a name="eachLimit" />
 208 ### eachLimit(arr, limit, iterator, callback)
 209
 210 The same as each only no more than "limit" iterators will be simultaneously
 211 running at any time.
 212
 213 Note that the items are not processed in batches, so there is no guarantee that
 214  the first "limit" iterator functions will complete before any others are
 215 started.
 216
 217 __Arguments__
 218
 219 * arr - An array to iterate over.
 220 * limit - The maximum number of iterators to run at any time.
 221 * iterator(item, callback) - A function to apply to each item in the array.
 222   The iterator is passed a callback(err) which must be called once it has
 223   completed. If no error has occured, the callback should be run without
 224   arguments or with an explicit null argument.
 225 * callback(err) - A callback which is called after all the iterator functions
 226   have finished, or an error has occurred.
 227
 228 __Example__
 229
 230 ```js
 231 // Assume documents is an array of JSON objects and requestApi is a
 232 // function that interacts with a rate-limited REST api.
 233
 234 async.eachLimit(documents, 20, requestApi, function(err){
 235     // if any of the saves produced an error, err would equal that error
 236 });
 237 ```
 238
 239 ---------------------------------------
 240
 241 <a name="map" />
 242 ### map(arr, iterator, callback)
 243
 244 Produces a new array of values by mapping each value in the given array through
 245 the iterator function. The iterator is called with an item from the array and a
 246 callback for when it has finished processing. The callback takes 2 arguments,
 247 an error and the transformed item from the array. If the iterator passes an
 248 error to this callback, the main callback for the map function is immediately
 249 called with the error.
 250
 251 Note, that since this function applies the iterator to each item in parallel
 252 there is no guarantee that the iterator functions will complete in order, however
 253 the results array will be in the same order as the original array.
 254
 255 __Arguments__
 256
 257 * arr - An array to iterate over.
 258 * iterator(item, callback) - A function to apply to each item in the array.
 259   The iterator is passed a callback(err, transformed) which must be called once
 260   it has completed with an error (which can be null) and a transformed item.
 261 * callback(err, results) - A callback which is called after all the iterator
 262   functions have finished, or an error has occurred. Results is an array of the
 263   transformed items from the original array.
 264
 265 __Example__
 266
 267 ```js
 268 async.map(['file1','file2','file3'], fs.stat, function(err, results){
 269     // results is now an array of stats for each file
 270 });
 271 ```
 272
 273 ---------------------------------------
 274
 275 <a name="mapSeries" />
 276 ### mapSeries(arr, iterator, callback)
 277
 278 The same as map only the iterator is applied to each item in the array in
 279 series. The next iterator is only called once the current one has completed
 280 processing. The results array will be in the same order as the original.
 281
 282
 283 ---------------------------------------
 284
 285 <a name="mapLimit" />
 286 ### mapLimit(arr, limit, iterator, callback)
 287
 288 The same as map only no more than "limit" iterators will be simultaneously
 289 running at any time.
 290
 291 Note that the items are not processed in batches, so there is no guarantee that
 292  the first "limit" iterator functions will complete before any others are
 293 started.
 294
 295 __Arguments__
 296
 297 * arr - An array to iterate over.
 298 * limit - The maximum number of iterators to run at any time.
 299 * iterator(item, callback) - A function to apply to each item in the array.
 300   The iterator is passed a callback(err, transformed) which must be called once
 301   it has completed with an error (which can be null) and a transformed item.
 302 * callback(err, results) - A callback which is called after all the iterator
 303   functions have finished, or an error has occurred. Results is an array of the
 304   transformed items from the original array.
 305
 306 __Example__
 307
 308 ```js
 309 async.mapLimit(['file1','file2','file3'], 1, fs.stat, function(err, results){
 310     // results is now an array of stats for each file
 311 });
 312 ```
 313
 314 ---------------------------------------
 315
 316 <a name="filter" />
 317 ### filter(arr, iterator, callback)
 318
 319 __Alias:__ select
 320
 321 Returns a new array of all the values which pass an async truth test.
 322 _The callback for each iterator call only accepts a single argument of true or
 323 false, it does not accept an error argument first!_ This is in-line with the
 324 way node libraries work with truth tests like fs.exists. This operation is
 325 performed in parallel, but the results array will be in the same order as the
 326 original.
 327
 328 __Arguments__
 329
 330 * arr - An array to iterate over.
 331 * iterator(item, callback) - A truth test to apply to each item in the array.
 332   The iterator is passed a callback(truthValue) which must be called with a
 333   boolean argument once it has completed.
 334 * callback(results) - A callback which is called after all the iterator
 335   functions have finished.
 336
 337 __Example__
 338
 339 ```js
 340 async.filter(['file1','file2','file3'], fs.exists, function(results){
 341     // results now equals an array of the existing files
 342 });
 343 ```
 344
 345 ---------------------------------------
 346
 347 <a name="filterSeries" />
 348 ### filterSeries(arr, iterator, callback)
 349
 350 __alias:__ selectSeries
 351
 352 The same as filter only the iterator is applied to each item in the array in
 353 series. The next iterator is only called once the current one has completed
 354 processing. The results array will be in the same order as the original.
 355
 356 ---------------------------------------
 357
 358 <a name="reject" />
 359 ### reject(arr, iterator, callback)
 360
 361 The opposite of filter. Removes values that pass an async truth test.
 362
 363 ---------------------------------------
 364
 365 <a name="rejectSeries" />
 366 ### rejectSeries(arr, iterator, callback)
 367
 368 The same as reject, only the iterator is applied to each item in the array
 369 in series.
 370
 371
 372 ---------------------------------------
 373
 374 <a name="reduce" />
 375 ### reduce(arr, memo, iterator, callback)
 376
 377 __aliases:__ inject, foldl
 378
 379 Reduces a list of values into a single value using an async iterator to return
 380 each successive step. Memo is the initial state of the reduction. This
 381 function only operates in series. For performance reasons, it may make sense to
 382 split a call to this function into a parallel map, then use the normal
 383 Array.prototype.reduce on the results. This function is for situations where
 384 each step in the reduction needs to be async, if you can get the data before
 385 reducing it then it's probably a good idea to do so.
 386
 387 __Arguments__
 388
 389 * arr - An array to iterate over.
 390 * memo - The initial state of the reduction.
 391 * iterator(memo, item, callback) - A function applied to each item in the
 392   array to produce the next step in the reduction. The iterator is passed a
 393   callback(err, reduction) which accepts an optional error as its first
 394   argument, and the state of the reduction as the second. If an error is
 395   passed to the callback, the reduction is stopped and the main callback is
 396   immediately called with the error.
 397 * callback(err, result) - A callback which is called after all the iterator
 398   functions have finished. Result is the reduced value.
 399
 400 __Example__
 401
 402 ```js
 403 async.reduce([1,2,3], 0, function(memo, item, callback){
 404     // pointless async:
 405     process.nextTick(function(){
 406         callback(null, memo + item)
 407     });
 408 }, function(err, result){
 409     // result is now equal to the last value of memo, which is 6
 410 });
 411 ```
 412
 413 ---------------------------------------
 414
 415 <a name="reduceRight" />
 416 ### reduceRight(arr, memo, iterator, callback)
 417
 418 __Alias:__ foldr
 419
 420 Same as reduce, only operates on the items in the array in reverse order.
 421
 422
 423 ---------------------------------------
 424
 425 <a name="detect" />
 426 ### detect(arr, iterator, callback)
 427
 428 Returns the first value in a list that passes an async truth test. The
 429 iterator is applied in parallel, meaning the first iterator to return true will
 430 fire the detect callback with that result. That means the result might not be
 431 the first item in the original array (in terms of order) that passes the test.
 432
 433 If order within the original array is important then look at detectSeries.
 434
 435 __Arguments__
 436
 437 * arr - An array to iterate over.
 438 * iterator(item, callback) - A truth test to apply to each item in the array.
 439   The iterator is passed a callback(truthValue) which must be called with a
 440   boolean argument once it has completed.
 441 * callback(result) - A callback which is called as soon as any iterator returns
 442   true, or after all the iterator functions have finished. Result will be
 443   the first item in the array that passes the truth test (iterator) or the
 444   value undefined if none passed.
 445
 446 __Example__
 447
 448 ```js
 449 async.detect(['file1','file2','file3'], fs.exists, function(result){
 450     // result now equals the first file in the list that exists
 451 });
 452 ```
 453
 454 ---------------------------------------
 455
 456 <a name="detectSeries" />
 457 ### detectSeries(arr, iterator, callback)
 458
 459 The same as detect, only the iterator is applied to each item in the array
 460 in series. This means the result is always the first in the original array (in
 461 terms of array order) that passes the truth test.
 462
 463
 464 ---------------------------------------
 465
 466 <a name="sortBy" />
 467 ### sortBy(arr, iterator, callback)
 468
 469 Sorts a list by the results of running each value through an async iterator.
 470
 471 __Arguments__
 472
 473 * arr - An array to iterate over.
 474 * iterator(item, callback) - A function to apply to each item in the array.
 475   The iterator is passed a callback(err, sortValue) which must be called once it
 476   has completed with an error (which can be null) and a value to use as the sort
 477   criteria.
 478 * callback(err, results) - A callback which is called after all the iterator
 479   functions have finished, or an error has occurred. Results is the items from
 480   the original array sorted by the values returned by the iterator calls.
 481
 482 __Example__
 483
 484 ```js
 485 async.sortBy(['file1','file2','file3'], function(file, callback){
 486     fs.stat(file, function(err, stats){
 487         callback(err, stats.mtime);
 488     });
 489 }, function(err, results){
 490     // results is now the original array of files sorted by
 491     // modified date
 492 });
 493 ```
 494
 495 ---------------------------------------
 496
 497 <a name="some" />
 498 ### some(arr, iterator, callback)
 499
 500 __Alias:__ any
 501
 502 Returns true if at least one element in the array satisfies an async test.
 503 _The callback for each iterator call only accepts a single argument of true or
 504 false, it does not accept an error argument first!_ This is in-line with the
 505 way node libraries work with truth tests like fs.exists. Once any iterator
 506 call returns true, the main callback is immediately called.
 507
 508 __Arguments__
 509
 510 * arr - An array to iterate over.
 511 * iterator(item, callback) - A truth test to apply to each item in the array.
 512   The iterator is passed a callback(truthValue) which must be called with a
 513   boolean argument once it has completed.
 514 * callback(result) - A callback which is called as soon as any iterator returns
 515   true, or after all the iterator functions have finished. Result will be
 516   either true or false depending on the values of the async tests.
 517
 518 __Example__
 519
 520 ```js
 521 async.some(['file1','file2','file3'], fs.exists, function(result){
 522     // if result is true then at least one of the files exists
 523 });
 524 ```
 525
 526 ---------------------------------------
 527
 528 <a name="every" />
 529 ### every(arr, iterator, callback)
 530
 531 __Alias:__ all
 532
 533 Returns true if every element in the array satisfies an async test.
 534 _The callback for each iterator call only accepts a single argument of true or
 535 false, it does not accept an error argument first!_ This is in-line with the
 536 way node libraries work with truth tests like fs.exists.
 537
 538 __Arguments__
 539
 540 * arr - An array to iterate over.
 541 * iterator(item, callback) - A truth test to apply to each item in the array.
 542   The iterator is passed a callback(truthValue) which must be called with a
 543   boolean argument once it has completed.
 544 * callback(result) - A callback which is called after all the iterator
 545   functions have finished. Result will be either true or false depending on
 546   the values of the async tests.
 547
 548 __Example__
 549
 550 ```js
 551 async.every(['file1','file2','file3'], fs.exists, function(result){
 552     // if result is true then every file exists
 553 });
 554 ```
 555
 556 ---------------------------------------
 557
 558 <a name="concat" />
 559 ### concat(arr, iterator, callback)
 560
 561 Applies an iterator to each item in a list, concatenating the results. Returns the
 562 concatenated list. The iterators are called in parallel, and the results are
 563 concatenated as they return. There is no guarantee that the results array will
 564 be returned in the original order of the arguments passed to the iterator function.
 565
 566 __Arguments__
 567
 568 * arr - An array to iterate over
 569 * iterator(item, callback) - A function to apply to each item in the array.
 570   The iterator is passed a callback(err, results) which must be called once it
 571   has completed with an error (which can be null) and an array of results.
 572 * callback(err, results) - A callback which is called after all the iterator
 573   functions have finished, or an error has occurred. Results is an array containing
 574   the concatenated results of the iterator function.
 575
 576 __Example__
 577
 578 ```js
 579 async.concat(['dir1','dir2','dir3'], fs.readdir, function(err, files){
 580     // files is now a list of filenames that exist in the 3 directories
 581 });
 582 ```
 583
 584 ---------------------------------------
 585
 586 <a name="concatSeries" />
 587 ### concatSeries(arr, iterator, callback)
 588
 589 Same as async.concat, but executes in series instead of parallel.
 590
 591
 592 ## Control Flow
 593
 594 <a name="series" />
 595 ### series(tasks, [callback])
 596
 597 Run an array of functions in series, each one running once the previous
 598 function has completed. If any functions in the series pass an error to its
 599 callback, no more functions are run and the callback for the series is
 600 immediately called with the value of the error. Once the tasks have completed,
 601 the results are passed to the final callback as an array.
 602
 603 It is also possible to use an object instead of an array. Each property will be
 604 run as a function and the results will be passed to the final callback as an object
 605 instead of an array. This can be a more readable way of handling results from
 606 async.series.
 607
 608
 609 __Arguments__
 610
 611 * tasks - An array or object containing functions to run, each function is passed
 612   a callback(err, result) it must call on completion with an error (which can
 613   be null) and an optional result value.
 614 * callback(err, results) - An optional callback to run once all the functions
 615   have completed. This function gets a results array (or object) containing all
 616   the result arguments passed to the task callbacks.
 617
 618 __Example__
 619
 620 ```js
 621 async.series([
 622     function(callback){
 623         // do some stuff ...
 624         callback(null, 'one');
 625     },
 626     function(callback){
 627         // do some more stuff ...
 628         callback(null, 'two');
 629     }
 630 ],
 631 // optional callback
 632 function(err, results){
 633     // results is now equal to ['one', 'two']
 634 });
 635
 636
 637 // an example using an object instead of an array
 638 async.series({
 639     one: function(callback){
 640         setTimeout(function(){
 641             callback(null, 1);
 642         }, 200);
 643     },
 644     two: function(callback){
 645         setTimeout(function(){
 646             callback(null, 2);
 647         }, 100);
 648     }
 649 },
 650 function(err, results) {
 651     // results is now equal to: {one: 1, two: 2}
 652 });
 653 ```
 654
 655 ---------------------------------------
 656
 657 <a name="parallel" />
 658 ### parallel(tasks, [callback])
 659
 660 Run an array of functions in parallel, without waiting until the previous
 661 function has completed. If any of the functions pass an error to its
 662 callback, the main callback is immediately called with the value of the error.
 663 Once the tasks have completed, the results are passed to the final callback as an
 664 array.
 665
 666 It is also possible to use an object instead of an array. Each property will be
 667 run as a function and the results will be passed to the final callback as an object
 668 instead of an array. This can be a more readable way of handling results from
 669 async.parallel.
 670
 671
 672 __Arguments__
 673
 674 * tasks - An array or object containing functions to run, each function is passed
 675   a callback(err, result) it must call on completion with an error (which can
 676   be null) and an optional result value.
 677 * callback(err, results) - An optional callback to run once all the functions
 678   have completed. This function gets a results array (or object) containing all
 679   the result arguments passed to the task callbacks.
 680
 681 __Example__
 682
 683 ```js
 684 async.parallel([
 685     function(callback){
 686         setTimeout(function(){
 687             callback(null, 'one');
 688         }, 200);
 689     },
 690     function(callback){
 691         setTimeout(function(){
 692             callback(null, 'two');
 693         }, 100);
 694     }
 695 ],
 696 // optional callback
 697 function(err, results){
 698     // the results array will equal ['one','two'] even though
 699     // the second function had a shorter timeout.
 700 });
 701
 702
 703 // an example using an object instead of an array
 704 async.parallel({
 705     one: function(callback){
 706         setTimeout(function(){
 707             callback(null, 1);
 708         }, 200);
 709     },
 710     two: function(callback){
 711         setTimeout(function(){
 712             callback(null, 2);
 713         }, 100);
 714     }
 715 },
 716 function(err, results) {
 717     // results is now equals to: {one: 1, two: 2}
 718 });
 719 ```
 720
 721 ---------------------------------------
 722
 723 <a name="parallel" />
 724 ### parallelLimit(tasks, limit, [callback])
 725
 726 The same as parallel only the tasks are executed in parallel with a maximum of "limit"
 727 tasks executing at any time.
 728
 729 Note that the tasks are not executed in batches, so there is no guarantee that
 730 the first "limit" tasks will complete before any others are started.
 731
 732 __Arguments__
 733
 734 * tasks - An array or object containing functions to run, each function is passed
 735   a callback(err, result) it must call on completion with an error (which can
 736   be null) and an optional result value.
 737 * limit - The maximum number of tasks to run at any time.
 738 * callback(err, results) - An optional callback to run once all the functions
 739   have completed. This function gets a results array (or object) containing all
 740   the result arguments passed to the task callbacks.
 741
 742 ---------------------------------------
 743
 744 <a name="whilst" />
 745 ### whilst(test, fn, callback)
 746
 747 Repeatedly call fn, while test returns true. Calls the callback when stopped,
 748 or an error occurs.
 749
 750 __Arguments__
 751
 752 * test() - synchronous truth test to perform before each execution of fn.
 753 * fn(callback) - A function to call each time the test passes. The function is
 754   passed a callback(err) which must be called once it has completed with an
 755   optional error argument.
 756 * callback(err) - A callback which is called after the test fails and repeated
 757   execution of fn has stopped.
 758
 759 __Example__
 760
 761 ```js
 762 var count = 0;
 763
 764 async.whilst(
 765     function () { return count < 5; },
 766     function (callback) {
 767         count++;
 768         setTimeout(callback, 1000);
 769     },
 770     function (err) {
 771         // 5 seconds have passed
 772     }
 773 );
 774 ```
 775
 776 ---------------------------------------
 777
 778 <a name="doWhilst" />
 779 ### doWhilst(fn, test, callback)
 780
 781 The post check version of whilst. To reflect the difference in the order of operations `test` and `fn` arguments are switched. `doWhilst` is to `whilst` as `do while` is to `while` in plain JavaScript.
 782
 783 ---------------------------------------
 784
 785 <a name="until" />
 786 ### until(test, fn, callback)
 787
 788 Repeatedly call fn, until test returns true. Calls the callback when stopped,
 789 or an error occurs.
 790
 791 The inverse of async.whilst.
 792
 793 ---------------------------------------
 794
 795 <a name="doUntil" />
 796 ### doUntil(fn, test, callback)
 797
 798 Like doWhilst except the test is inverted. Note the argument ordering differs from `until`.
 799
 800 ---------------------------------------
 801
 802 <a name="forever" />
 803 ### forever(fn, callback)
 804
 805 Calls the asynchronous function 'fn' repeatedly, in series, indefinitely.
 806 If an error is passed to fn's callback then 'callback' is called with the
 807 error, otherwise it will never be called.
 808
 809 ---------------------------------------
 810
 811 <a name="waterfall" />
 812 ### waterfall(tasks, [callback])
 813
 814 Runs an array of functions in series, each passing their results to the next in
 815 the array. However, if any of the functions pass an error to the callback, the
 816 next function is not executed and the main callback is immediately called with
 817 the error.
 818
 819 __Arguments__
 820
 821 * tasks - An array of functions to run, each function is passed a
 822   callback(err, result1, result2, ...) it must call on completion. The first
 823   argument is an error (which can be null) and any further arguments will be
 824   passed as arguments in order to the next task.
 825 * callback(err, [results]) - An optional callback to run once all the functions
 826   have completed. This will be passed the results of the last task's callback.
 827
 828
 829
 830 __Example__
 831
 832 ```js
 833 async.waterfall([
 834     function(callback){
 835         callback(null, 'one', 'two');
 836     },
 837     function(arg1, arg2, callback){
 838         callback(null, 'three');
 839     },
 840     function(arg1, callback){
 841         // arg1 now equals 'three'
 842         callback(null, 'done');
 843     }
 844 ], function (err, result) {
 845    // result now equals 'done'
 846 });
 847 ```
 848
 849 ---------------------------------------
 850 <a name="compose" />
 851 ### compose(fn1, fn2...)
 852
 853 Creates a function which is a composition of the passed asynchronous
 854 functions. Each function consumes the return value of the function that
 855 follows. Composing functions f(), g() and h() would produce the result of
 856 f(g(h())), only this version uses callbacks to obtain the return values.
 857
 858 Each function is executed with the `this` binding of the composed function.
 859
 860 __Arguments__
 861
 862 * functions... - the asynchronous functions to compose
 863
 864
 865 __Example__
 866
 867 ```js
 868 function add1(n, callback) {
 869     setTimeout(function () {
 870         callback(null, n + 1);
 871     }, 10);
 872 }
 873
 874 function mul3(n, callback) {
 875     setTimeout(function () {
 876         callback(null, n * 3);
 877     }, 10);
 878 }
 879
 880 var add1mul3 = async.compose(mul3, add1);
 881
 882 add1mul3(4, function (err, result) {
 883    // result now equals 15
 884 });
 885 ```
 886
 887 ---------------------------------------
 888 <a name="applyEach" />
 889 ### applyEach(fns, args..., callback)
 890
 891 Applies the provided arguments to each function in the array, calling the
 892 callback after all functions have completed. If you only provide the first
 893 argument then it will return a function which lets you pass in the
 894 arguments as if it were a single function call.
 895
 896 __Arguments__
 897
 898 * fns - the asynchronous functions to all call with the same arguments
 899 * args... - any number of separate arguments to pass to the function
 900 * callback - the final argument should be the callback, called when all
 901   functions have completed processing
 902
 903
 904 __Example__
 905
 906 ```js
 907 async.applyEach([enableSearch, updateSchema], 'bucket', callback);
 908
 909 // partial application example:
 910 async.each(
 911     buckets,
 912     async.applyEach([enableSearch, updateSchema]),
 913     callback
 914 );
 915 ```
 916
 917 ---------------------------------------
 918
 919 <a name="applyEachSeries" />
 920 ### applyEachSeries(arr, iterator, callback)
 921
 922 The same as applyEach only the functions are applied in series.
 923
 924 ---------------------------------------
 925
 926 <a name="queue" />
 927 ### queue(worker, concurrency)
 928
 929 Creates a queue object with the specified concurrency. Tasks added to the
 930 queue will be processed in parallel (up to the concurrency limit). If all
 931 workers are in progress, the task is queued until one is available. Once
 932 a worker has completed a task, the task's callback is called.
 933
 934 __Arguments__
 935
 936 * worker(task, callback) - An asynchronous function for processing a queued
 937   task, which must call its callback(err) argument when finished, with an
 938   optional error as an argument.
 939 * concurrency - An integer for determining how many worker functions should be
 940   run in parallel.
 941
 942 __Queue objects__
 943
 944 The queue object returned by this function has the following properties and
 945 methods:
 946
 947 * length() - a function returning the number of items waiting to be processed.
 948 * concurrency - an integer for determining how many worker functions should be
 949   run in parallel. This property can be changed after a queue is created to
 950   alter the concurrency on-the-fly.
 951 * push(task, [callback]) - add a new task to the queue, the callback is called
 952   once the worker has finished processing the task.
 953   instead of a single task, an array of tasks can be submitted. the respective callback is used for every task in the list.
 954 * unshift(task, [callback]) - add a new task to the front of the queue.
 955 * saturated - a callback that is called when the queue length hits the concurrency and further tasks will be queued
 956 * empty - a callback that is called when the last item from the queue is given to a worker
 957 * drain - a callback that is called when the last item from the queue has returned from the worker
 958
 959 __Example__
 960
 961 ```js
 962 // create a queue object with concurrency 2
 963
 964 var q = async.queue(function (task, callback) {
 965     console.log('hello ' + task.name);
 966     callback();
 967 }, 2);
 968
 969
 970 // assign a callback
 971 q.drain = function() {
 972     console.log('all items have been processed');
 973 }
 974
 975 // add some items to the queue
 976
 977 q.push({name: 'foo'}, function (err) {
 978     console.log('finished processing foo');
 979 });
 980 q.push({name: 'bar'}, function (err) {
 981     console.log('finished processing bar');
 982 });
 983
 984 // add some items to the queue (batch-wise)
 985
 986 q.push([{name: 'baz'},{name: 'bay'},{name: 'bax'}], function (err) {
 987     console.log('finished processing bar');
 988 });
 989
 990 // add some items to the front of the queue
 991
 992 q.unshift({name: 'bar'}, function (err) {
 993     console.log('finished processing bar');
 994 });
 995 ```
 996
 997 ---------------------------------------
 998
 999 <a name="cargo" />
1000 ### cargo(worker, [payload])
1001
1002 Creates a cargo object with the specified payload. Tasks added to the
1003 cargo will be processed altogether (up to the payload limit). If the
1004 worker is in progress, the task is queued until it is available. Once
1005 the worker has completed some tasks, each callback of those tasks is called.
1006
1007 __Arguments__
1008
1009 * worker(tasks, callback) - An asynchronous function for processing an array of
1010   queued tasks, which must call its callback(err) argument when finished, with
1011   an optional error as an argument.
1012 * payload - An optional integer for determining how many tasks should be
1013   processed per round; if omitted, the default is unlimited.
1014
1015 __Cargo objects__
1016
1017 The cargo object returned by this function has the following properties and
1018 methods:
1019
1020 * length() - a function returning the number of items waiting to be processed.
1021 * payload - an integer for determining how many tasks should be
1022   process per round. This property can be changed after a cargo is created to
1023   alter the payload on-the-fly.
1024 * push(task, [callback]) - add a new task to the queue, the callback is called
1025   once the worker has finished processing the task.
1026   instead of a single task, an array of tasks can be submitted. the respective callback is used for every task in the list.
1027 * saturated - a callback that is called when the queue length hits the concurrency and further tasks will be queued
1028 * empty - a callback that is called when the last item from the queue is given to a worker
1029 * drain - a callback that is called when the last item from the queue has returned from the worker
1030
1031 __Example__
1032
1033 ```js
1034 // create a cargo object with payload 2
1035
1036 var cargo = async.cargo(function (tasks, callback) {
1037     for(var i=0; i<tasks.length; i++){
1038       console.log('hello ' + tasks[i].name);
1039     }
1040     callback();
1041 }, 2);
1042
1043
1044 // add some items
1045
1046 cargo.push({name: 'foo'}, function (err) {
1047     console.log('finished processing foo');
1048 });
1049 cargo.push({name: 'bar'}, function (err) {
1050     console.log('finished processing bar');
1051 });
1052 cargo.push({name: 'baz'}, function (err) {
1053     console.log('finished processing baz');
1054 });
1055 ```
1056
1057 ---------------------------------------
1058
1059 <a name="auto" />
1060 ### auto(tasks, [callback])
1061
1062 Determines the best order for running functions based on their requirements.
1063 Each function can optionally depend on other functions being completed first,
1064 and each function is run as soon as its requirements are satisfied. If any of
1065 the functions pass an error to their callback, that function will not complete
1066 (so any other functions depending on it will not run) and the main callback
1067 will be called immediately with the error. Functions also receive an object
1068 containing the results of functions which have completed so far.
1069
1070 Note, all functions are called with a results object as a second argument,
1071 so it is unsafe to pass functions in the tasks object which cannot handle the
1072 extra argument. For example, this snippet of code:
1073
1074 ```js
1075 async.auto({
1076   readData: async.apply(fs.readFile, 'data.txt', 'utf-8')
1077 }, callback);
1078 ```
1079
1080 will have the effect of calling readFile with the results object as the last
1081 argument, which will fail:
1082
1083 ```js
1084 fs.readFile('data.txt', 'utf-8', cb, {});
1085 ```
1086
1087 Instead, wrap the call to readFile in a function which does not forward the
1088 results object:
1089
1090 ```js
1091 async.auto({
1092   readData: function(cb, results){
1093     fs.readFile('data.txt', 'utf-8', cb);
1094   }
1095 }, callback);
1096 ```
1097
1098 __Arguments__
1099
1100 * tasks - An object literal containing named functions or an array of
1101   requirements, with the function itself the last item in the array. The key
1102   used for each function or array is used when specifying requirements. The
1103   function receives two arguments: (1) a callback(err, result) which must be
1104   called when finished, passing an error (which can be null) and the result of
1105   the function's execution, and (2) a results object, containing the results of
1106   the previously executed functions.
1107 * callback(err, results) - An optional callback which is called when all the
1108   tasks have been completed. The callback will receive an error as an argument
1109   if any tasks pass an error to their callback. Results will always be passed
1110         but if an error occurred, no other tasks will be performed, and the results
1111         object will only contain partial results.
1112
1113
1114 __Example__
1115
1116 ```js
1117 async.auto({
1118     get_data: function(callback){
1119         // async code to get some data
1120     },
1121     make_folder: function(callback){
1122         // async code to create a directory to store a file in
1123         // this is run at the same time as getting the data
1124     },
1125     write_file: ['get_data', 'make_folder', function(callback){
1126         // once there is some data and the directory exists,
1127         // write the data to a file in the directory
1128         callback(null, filename);
1129     }],
1130     email_link: ['write_file', function(callback, results){
1131         // once the file is written let's email a link to it...
1132         // results.write_file contains the filename returned by write_file.
1133     }]
1134 });
1135 ```
1136
1137 This is a fairly trivial example, but to do this using the basic parallel and
1138 series functions would look like this:
1139
1140 ```js
1141 async.parallel([
1142     function(callback){
1143         // async code to get some data
1144     },
1145     function(callback){
1146         // async code to create a directory to store a file in
1147         // this is run at the same time as getting the data
1148     }
1149 ],
1150 function(err, results){
1151     async.series([
1152         function(callback){
1153             // once there is some data and the directory exists,
1154             // write the data to a file in the directory
1155         },
1156         function(callback){
1157             // once the file is written let's email a link to it...
1158         }
1159     ]);
1160 });
1161 ```
1162
1163 For a complicated series of async tasks using the auto function makes adding
1164 new tasks much easier and makes the code more readable.
1165
1166
1167 ---------------------------------------
1168
1169 <a name="iterator" />
1170 ### iterator(tasks)
1171
1172 Creates an iterator function which calls the next function in the array,
1173 returning a continuation to call the next one after that. It's also possible to
1174 'peek' the next iterator by doing iterator.next().
1175
1176 This function is used internally by the async module but can be useful when
1177 you want to manually control the flow of functions in series.
1178
1179 __Arguments__
1180
1181 * tasks - An array of functions to run.
1182
1183 __Example__
1184
1185 ```js
1186 var iterator = async.iterator([
1187     function(){ sys.p('one'); },
1188     function(){ sys.p('two'); },
1189     function(){ sys.p('three'); }
1190 ]);
1191
1192 node> var iterator2 = iterator();
1193 'one'
1194 node> var iterator3 = iterator2();
1195 'two'
1196 node> iterator3();
1197 'three'
1198 node> var nextfn = iterator2.next();
1199 node> nextfn();
1200 'three'
1201 ```
1202
1203 ---------------------------------------
1204
1205 <a name="apply" />
1206 ### apply(function, arguments..)
1207
1208 Creates a continuation function with some arguments already applied, a useful
1209 shorthand when combined with other control flow functions. Any arguments
1210 passed to the returned function are added to the arguments originally passed
1211 to apply.
1212
1213 __Arguments__
1214
1215 * function - The function you want to eventually apply all arguments to.
1216 * arguments... - Any number of arguments to automatically apply when the
1217   continuation is called.
1218
1219 __Example__
1220
1221 ```js
1222 // using apply
1223
1224 async.parallel([
1225     async.apply(fs.writeFile, 'testfile1', 'test1'),
1226     async.apply(fs.writeFile, 'testfile2', 'test2'),
1227 ]);
1228
1229
1230 // the same process without using apply
1231
1232 async.parallel([
1233     function(callback){
1234         fs.writeFile('testfile1', 'test1', callback);
1235     },
1236     function(callback){
1237         fs.writeFile('testfile2', 'test2', callback);
1238     }
1239 ]);
1240 ```
1241
1242 It's possible to pass any number of additional arguments when calling the
1243 continuation:
1244
1245 ```js
1246 node> var fn = async.apply(sys.puts, 'one');
1247 node> fn('two', 'three');
1248 one
1249 two
1250 three
1251 ```
1252
1253 ---------------------------------------
1254
1255 <a name="nextTick" />
1256 ### nextTick(callback)
1257
1258 Calls the callback on a later loop around the event loop. In node.js this just
1259 calls process.nextTick, in the browser it falls back to setImmediate(callback)
1260 if available, otherwise setTimeout(callback, 0), which means other higher priority
1261 events may precede the execution of the callback.
1262
1263 This is used internally for browser-compatibility purposes.
1264
1265 __Arguments__
1266
1267 * callback - The function to call on a later loop around the event loop.
1268
1269 __Example__
1270
1271 ```js
1272 var call_order = [];
1273 async.nextTick(function(){
1274     call_order.push('two');
1275     // call_order now equals ['one','two']
1276 });
1277 call_order.push('one')
1278 ```
1279
1280 <a name="times" />
1281 ### times(n, callback)
1282
1283 Calls the callback n times and accumulates results in the same manner
1284 you would use with async.map.
1285
1286 __Arguments__
1287
1288 * n - The number of times to run the function.
1289 * callback - The function to call n times.
1290
1291 __Example__
1292
1293 ```js
1294 // Pretend this is some complicated async factory
1295 var createUser = function(id, callback) {
1296   callback(null, {
1297     id: 'user' + id
1298   })
1299 }
1300 // generate 5 users
1301 async.times(5, function(n, next){
1302     createUser(n, function(err, user) {
1303       next(err, user)
1304     })
1305 }, function(err, users) {
1306   // we should now have 5 users
1307 });
1308 ```
1309
1310 <a name="timesSeries" />
1311 ### timesSeries(n, callback)
1312
1313 The same as times only the iterator is applied to each item in the array in
1314 series. The next iterator is only called once the current one has completed
1315 processing. The results array will be in the same order as the original.
1316
1317
1318 ## Utils
1319
1320 <a name="memoize" />
1321 ### memoize(fn, [hasher])
1322
1323 Caches the results of an async function. When creating a hash to store function
1324 results against, the callback is omitted from the hash and an optional hash
1325 function can be used.
1326
1327 The cache of results is exposed as the `memo` property of the function returned
1328 by `memoize`.
1329
1330 __Arguments__
1331
1332 * fn - the function you to proxy and cache results from.
1333 * hasher - an optional function for generating a custom hash for storing
1334   results, it has all the arguments applied to it apart from the callback, and
1335   must be synchronous.
1336
1337 __Example__
1338
1339 ```js
1340 var slow_fn = function (name, callback) {
1341     // do something
1342     callback(null, result);
1343 };
1344 var fn = async.memoize(slow_fn);
1345
1346 // fn can now be used as if it were slow_fn
1347 fn('some name', function () {
1348     // callback
1349 });
1350 ```
1351
1352 <a name="unmemoize" />
1353 ### unmemoize(fn)
1354
1355 Undoes a memoized function, reverting it to the original, unmemoized
1356 form. Comes handy in tests.
1357
1358 __Arguments__
1359
1360 * fn - the memoized function
1361
1362 <a name="log" />
1363 ### log(function, arguments)
1364
1365 Logs the result of an async function to the console. Only works in node.js or
1366 in browsers that support console.log and console.error (such as FF and Chrome).
1367 If multiple arguments are returned from the async function, console.log is
1368 called on each argument in order.
1369
1370 __Arguments__
1371
1372 * function - The function you want to eventually apply all arguments to.
1373 * arguments... - Any number of arguments to apply to the function.
1374
1375 __Example__
1376
1377 ```js
1378 var hello = function(name, callback){
1379     setTimeout(function(){
1380         callback(null, 'hello ' + name);
1381     }, 1000);
1382 };
1383 ```
1384 ```js
1385 node> async.log(hello, 'world');
1386 'hello world'
1387 ```
1388
1389 ---------------------------------------
1390
1391 <a name="dir" />
1392 ### dir(function, arguments)
1393
1394 Logs the result of an async function to the console using console.dir to
1395 display the properties of the resulting object. Only works in node.js or
1396 in browsers that support console.dir and console.error (such as FF and Chrome).
1397 If multiple arguments are returned from the async function, console.dir is
1398 called on each argument in order.
1399
1400 __Arguments__
1401
1402 * function - The function you want to eventually apply all arguments to.
1403 * arguments... - Any number of arguments to apply to the function.
1404
1405 __Example__
1406
1407 ```js
1408 var hello = function(name, callback){
1409     setTimeout(function(){
1410         callback(null, {hello: name});
1411     }, 1000);
1412 };
1413 ```
1414 ```js
1415 node> async.dir(hello, 'world');
1416 {hello: 'world'}
1417 ```
1418
1419 ---------------------------------------
1420
1421 <a name="noConflict" />
1422 ### noConflict()
1423
1424 Changes the value of async back to its original value, returning a reference to the
1425 async object.