libs/js/jquery-mobile-1.2.0/node_modules/grunt/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.
   7
   8 Async provides around 20 functions that include the usual 'functional'
   9 suspects (map, reduce, filter, forEach…) 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     async.map(['file1','file2','file3'], fs.stat, function(err, results){
  18         // results is now an array of stats for each file
  19     });
  20
  21     async.filter(['file1','file2','file3'], path.exists, function(results){
  22         // results now equals an array of the existing files
  23     });
  24
  25     async.parallel([
  26         function(){ ... },
  27         function(){ ... }
  28     ], callback);
  29
  30     async.series([
  31         function(){ ... },
  32         function(){ ... }
  33     ]);
  34
  35 There are many more functions available so take a look at the docs below for a
  36 full list. This module aims to be comprehensive, so if you feel anything is
  37 missing please create a GitHub issue for it.
  38
  39
  40 ## Download
  41
  42 Releases are available for download from
  43 [GitHub](http://github.com/caolan/async/downloads).
  44 Alternatively, you can install using Node Package Manager (npm):
  45
  46     npm install async
  47
  48
  49 __Development:__ [async.js](https://github.com/caolan/async/raw/master/lib/async.js) - 17.5kb Uncompressed
  50
  51 __Production:__ [async.min.js](https://github.com/caolan/async/raw/master/dist/async.min.js) - 1.7kb Packed and Gzipped
  52
  53
  54 ## In the Browser
  55
  56 So far its been tested in IE6, IE7, IE8, FF3.6 and Chrome 5. Usage:
  57
  58     <script type="text/javascript" src="async.js"></script>
  59     <script type="text/javascript">
  60
  61         async.map(data, asyncProcess, function(err, results){
  62             alert(results);
  63         });
  64
  65     </script>
  66
  67
  68 ## Documentation
  69
  70 ### Collections
  71
  72 * [forEach](#forEach)
  73 * [map](#map)
  74 * [filter](#filter)
  75 * [reject](#reject)
  76 * [reduce](#reduce)
  77 * [detect](#detect)
  78 * [sortBy](#sortBy)
  79 * [some](#some)
  80 * [every](#every)
  81 * [concat](#concat)
  82
  83 ### Control Flow
  84
  85 * [series](#series)
  86 * [parallel](#parallel)
  87 * [whilst](#whilst)
  88 * [until](#until)
  89 * [waterfall](#waterfall)
  90 * [queue](#queue)
  91 * [auto](#auto)
  92 * [iterator](#iterator)
  93 * [apply](#apply)
  94 * [nextTick](#nextTick)
  95
  96 ### Utils
  97
  98 * [memoize](#memoize)
  99 * [unmemoize](#unmemoize)
 100 * [log](#log)
 101 * [dir](#dir)
 102 * [noConflict](#noConflict)
 103
 104
 105 ## Collections
 106
 107 <a name="forEach" />
 108 ### forEach(arr, iterator, callback)
 109
 110 Applies an iterator function to each item in an array, in parallel.
 111 The iterator is called with an item from the list and a callback for when it
 112 has finished. If the iterator passes an error to this callback, the main
 113 callback for the forEach function is immediately called with the error.
 114
 115 Note, that since this function applies the iterator to each item in parallel
 116 there is no guarantee that the iterator functions will complete in order.
 117
 118 __Arguments__
 119
 120 * arr - An array to iterate over.
 121 * iterator(item, callback) - A function to apply to each item in the array.
 122   The iterator is passed a callback which must be called once it has completed.
 123 * callback(err) - A callback which is called after all the iterator functions
 124   have finished, or an error has occurred.
 125
 126 __Example__
 127
 128     // assuming openFiles is an array of file names and saveFile is a function
 129     // to save the modified contents of that file:
 130
 131     async.forEach(openFiles, saveFile, function(err){
 132         // if any of the saves produced an error, err would equal that error
 133     });
 134
 135 ---------------------------------------
 136
 137 <a name="forEachSeries" />
 138 ### forEachSeries(arr, iterator, callback)
 139
 140 The same as forEach only the iterator is applied to each item in the array in
 141 series. The next iterator is only called once the current one has completed
 142 processing. This means the iterator functions will complete in order.
 143
 144
 145 ---------------------------------------
 146
 147 <a name="forEachLimit" />
 148 ### forEachLimit(arr, limit, iterator, callback)
 149
 150 The same as forEach only the iterator is applied to batches of items in the
 151 array, in series. The next batch of iterators is only called once the current
 152 one has completed processing.
 153
 154 __Arguments__
 155
 156 * arr - An array to iterate over.
 157 * limit - How many items should be in each batch.
 158 * iterator(item, callback) - A function to apply to each item in the array.
 159   The iterator is passed a callback which must be called once it has completed.
 160 * callback(err) - A callback which is called after all the iterator functions
 161   have finished, or an error has occurred.
 162
 163 __Example__
 164
 165     // Assume documents is an array of JSON objects and requestApi is a
 166     // function that interacts with a rate-limited REST api.
 167
 168     async.forEachLimit(documents, 20, requestApi, function(err){
 169         // if any of the saves produced an error, err would equal that error
 170     });
 171 ---------------------------------------
 172
 173 <a name="map" />
 174 ### map(arr, iterator, callback)
 175
 176 Produces a new array of values by mapping each value in the given array through
 177 the iterator function. The iterator is called with an item from the array and a
 178 callback for when it has finished processing. The callback takes 2 arguments,
 179 an error and the transformed item from the array. If the iterator passes an
 180 error to this callback, the main callback for the map function is immediately
 181 called with the error.
 182
 183 Note, that since this function applies the iterator to each item in parallel
 184 there is no guarantee that the iterator functions will complete in order, however
 185 the results array will be in the same order as the original array.
 186
 187 __Arguments__
 188
 189 * arr - An array to iterate over.
 190 * iterator(item, callback) - A function to apply to each item in the array.
 191   The iterator is passed a callback which must be called once it has completed
 192   with an error (which can be null) and a transformed item.
 193 * callback(err, results) - A callback which is called after all the iterator
 194   functions have finished, or an error has occurred. Results is an array of the
 195   transformed items from the original array.
 196
 197 __Example__
 198
 199     async.map(['file1','file2','file3'], fs.stat, function(err, results){
 200         // results is now an array of stats for each file
 201     });
 202
 203 ---------------------------------------
 204
 205 <a name="mapSeries" />
 206 ### mapSeries(arr, iterator, callback)
 207
 208 The same as map only the iterator is applied to each item in the array in
 209 series. The next iterator is only called once the current one has completed
 210 processing. The results array will be in the same order as the original.
 211
 212
 213 ---------------------------------------
 214
 215 <a name="filter" />
 216 ### filter(arr, iterator, callback)
 217
 218 __Alias:__ select
 219
 220 Returns a new array of all the values which pass an async truth test.
 221 _The callback for each iterator call only accepts a single argument of true or
 222 false, it does not accept an error argument first!_ This is in-line with the
 223 way node libraries work with truth tests like path.exists. This operation is
 224 performed in parallel, but the results array will be in the same order as the
 225 original.
 226
 227 __Arguments__
 228
 229 * arr - An array to iterate over.
 230 * iterator(item, callback) - A truth test to apply to each item in the array.
 231   The iterator is passed a callback which must be called once it has completed.
 232 * callback(results) - A callback which is called after all the iterator
 233   functions have finished.
 234
 235 __Example__
 236
 237     async.filter(['file1','file2','file3'], path.exists, function(results){
 238         // results now equals an array of the existing files
 239     });
 240
 241 ---------------------------------------
 242
 243 <a name="filterSeries" />
 244 ### filterSeries(arr, iterator, callback)
 245
 246 __alias:__ selectSeries
 247
 248 The same as filter only the iterator is applied to each item in the array in
 249 series. The next iterator is only called once the current one has completed
 250 processing. The results array will be in the same order as the original.
 251
 252 ---------------------------------------
 253
 254 <a name="reject" />
 255 ### reject(arr, iterator, callback)
 256
 257 The opposite of filter. Removes values that pass an async truth test.
 258
 259 ---------------------------------------
 260
 261 <a name="rejectSeries" />
 262 ### rejectSeries(arr, iterator, callback)
 263
 264 The same as filter, only the iterator is applied to each item in the array
 265 in series.
 266
 267
 268 ---------------------------------------
 269
 270 <a name="reduce" />
 271 ### reduce(arr, memo, iterator, callback)
 272
 273 __aliases:__ inject, foldl
 274
 275 Reduces a list of values into a single value using an async iterator to return
 276 each successive step. Memo is the initial state of the reduction. This
 277 function only operates in series. For performance reasons, it may make sense to
 278 split a call to this function into a parallel map, then use the normal
 279 Array.prototype.reduce on the results. This function is for situations where
 280 each step in the reduction needs to be async, if you can get the data before
 281 reducing it then its probably a good idea to do so.
 282
 283 __Arguments__
 284
 285 * arr - An array to iterate over.
 286 * memo - The initial state of the reduction.
 287 * iterator(memo, item, callback) - A function applied to each item in the
 288   array to produce the next step in the reduction. The iterator is passed a
 289   callback which accepts an optional error as its first argument, and the state
 290   of the reduction as the second. If an error is passed to the callback, the
 291   reduction is stopped and the main callback is immediately called with the
 292   error.
 293 * callback(err, result) - A callback which is called after all the iterator
 294   functions have finished. Result is the reduced value.
 295
 296 __Example__
 297
 298     async.reduce([1,2,3], 0, function(memo, item, callback){
 299         // pointless async:
 300         process.nextTick(function(){
 301             callback(null, memo + item)
 302         });
 303     }, function(err, result){
 304         // result is now equal to the last value of memo, which is 6
 305     });
 306
 307 ---------------------------------------
 308
 309 <a name="reduceRight" />
 310 ### reduceRight(arr, memo, iterator, callback)
 311
 312 __Alias:__ foldr
 313
 314 Same as reduce, only operates on the items in the array in reverse order.
 315
 316
 317 ---------------------------------------
 318
 319 <a name="detect" />
 320 ### detect(arr, iterator, callback)
 321
 322 Returns the first value in a list that passes an async truth test. The
 323 iterator is applied in parallel, meaning the first iterator to return true will
 324 fire the detect callback with that result. That means the result might not be
 325 the first item in the original array (in terms of order) that passes the test.
 326
 327 If order within the original array is important then look at detectSeries.
 328
 329 __Arguments__
 330
 331 * arr - An array to iterate over.
 332 * iterator(item, callback) - A truth test to apply to each item in the array.
 333   The iterator is passed a callback which must be called once it has completed.
 334 * callback(result) - A callback which is called as soon as any iterator returns
 335   true, or after all the iterator functions have finished. Result will be
 336   the first item in the array that passes the truth test (iterator) or the
 337   value undefined if none passed.
 338
 339 __Example__
 340
 341     async.detect(['file1','file2','file3'], path.exists, function(result){
 342         // result now equals the first file in the list that exists
 343     });
 344
 345 ---------------------------------------
 346
 347 <a name="detectSeries" />
 348 ### detectSeries(arr, iterator, callback)
 349
 350 The same as detect, only the iterator is applied to each item in the array
 351 in series. This means the result is always the first in the original array (in
 352 terms of array order) that passes the truth test.
 353
 354
 355 ---------------------------------------
 356
 357 <a name="sortBy" />
 358 ### sortBy(arr, iterator, callback)
 359
 360 Sorts a list by the results of running each value through an async iterator.
 361
 362 __Arguments__
 363
 364 * arr - An array to iterate over.
 365 * iterator(item, callback) - A function to apply to each item in the array.
 366   The iterator is passed a callback which must be called once it has completed
 367   with an error (which can be null) and a value to use as the sort criteria.
 368 * callback(err, results) - A callback which is called after all the iterator
 369   functions have finished, or an error has occurred. Results is the items from
 370   the original array sorted by the values returned by the iterator calls.
 371
 372 __Example__
 373
 374     async.sortBy(['file1','file2','file3'], function(file, callback){
 375         fs.stat(file, function(err, stats){
 376             callback(err, stats.mtime);
 377         });
 378     }, function(err, results){
 379         // results is now the original array of files sorted by
 380         // modified date
 381     });
 382
 383
 384 ---------------------------------------
 385
 386 <a name="some" />
 387 ### some(arr, iterator, callback)
 388
 389 __Alias:__ any
 390
 391 Returns true if at least one element in the array satisfies an async test.
 392 _The callback for each iterator call only accepts a single argument of true or
 393 false, it does not accept an error argument first!_ This is in-line with the
 394 way node libraries work with truth tests like path.exists. Once any iterator
 395 call returns true, the main callback is immediately called.
 396
 397 __Arguments__
 398
 399 * arr - An array to iterate over.
 400 * iterator(item, callback) - A truth test to apply to each item in the array.
 401   The iterator is passed a callback which must be called once it has completed.
 402 * callback(result) - A callback which is called as soon as any iterator returns
 403   true, or after all the iterator functions have finished. Result will be
 404   either true or false depending on the values of the async tests.
 405
 406 __Example__
 407
 408     async.some(['file1','file2','file3'], path.exists, function(result){
 409         // if result is true then at least one of the files exists
 410     });
 411
 412 ---------------------------------------
 413
 414 <a name="every" />
 415 ### every(arr, iterator, callback)
 416
 417 __Alias:__ all
 418
 419 Returns true if every element in the array satisfies an async test.
 420 _The callback for each iterator call only accepts a single argument of true or
 421 false, it does not accept an error argument first!_ This is in-line with the
 422 way node libraries work with truth tests like path.exists.
 423
 424 __Arguments__
 425
 426 * arr - An array to iterate over.
 427 * iterator(item, callback) - A truth test to apply to each item in the array.
 428   The iterator is passed a callback which must be called once it has completed.
 429 * callback(result) - A callback which is called after all the iterator
 430   functions have finished. Result will be either true or false depending on
 431   the values of the async tests.
 432
 433 __Example__
 434
 435     async.every(['file1','file2','file3'], path.exists, function(result){
 436         // if result is true then every file exists
 437     });
 438
 439 ---------------------------------------
 440
 441 <a name="concat" />
 442 ### concat(arr, iterator, callback)
 443
 444 Applies an iterator to each item in a list, concatenating the results. Returns the
 445 concatenated list. The iterators are called in parallel, and the results are
 446 concatenated as they return. There is no guarantee that the results array will
 447 be returned in the original order of the arguments passed to the iterator function.
 448
 449 __Arguments__
 450
 451 * arr - An array to iterate over
 452 * iterator(item, callback) - A function to apply to each item in the array.
 453   The iterator is passed a callback which must be called once it has completed
 454   with an error (which can be null) and an array of results.
 455 * callback(err, results) - A callback which is called after all the iterator
 456   functions have finished, or an error has occurred. Results is an array containing
 457   the concatenated results of the iterator function.
 458
 459 __Example__
 460
 461     async.concat(['dir1','dir2','dir3'], fs.readdir, function(err, files){
 462         // files is now a list of filenames that exist in the 3 directories
 463     });
 464
 465 ---------------------------------------
 466
 467 <a name="concatSeries" />
 468 ### concatSeries(arr, iterator, callback)
 469
 470 Same as async.concat, but executes in series instead of parallel.
 471
 472
 473 ## Control Flow
 474
 475 <a name="series" />
 476 ### series(tasks, [callback])
 477
 478 Run an array of functions in series, each one running once the previous
 479 function has completed. If any functions in the series pass an error to its
 480 callback, no more functions are run and the callback for the series is
 481 immediately called with the value of the error. Once the tasks have completed,
 482 the results are passed to the final callback as an array.
 483
 484 It is also possible to use an object instead of an array. Each property will be
 485 run as a function and the results will be passed to the final callback as an object
 486 instead of an array. This can be a more readable way of handling results from
 487 async.series.
 488
 489
 490 __Arguments__
 491
 492 * tasks - An array or object containing functions to run, each function is passed
 493   a callback it must call on completion.
 494 * callback(err, results) - An optional callback to run once all the functions
 495   have completed. This function gets an array of all the arguments passed to
 496   the callbacks used in the array.
 497
 498 __Example__
 499
 500     async.series([
 501         function(callback){
 502             // do some stuff ...
 503             callback(null, 'one');
 504         },
 505         function(callback){
 506             // do some more stuff ...
 507             callback(null, 'two');
 508         },
 509     ],
 510     // optional callback
 511     function(err, results){
 512         // results is now equal to ['one', 'two']
 513     });
 514
 515
 516     // an example using an object instead of an array
 517     async.series({
 518         one: function(callback){
 519             setTimeout(function(){
 520                 callback(null, 1);
 521             }, 200);
 522         },
 523         two: function(callback){
 524             setTimeout(function(){
 525                 callback(null, 2);
 526             }, 100);
 527         },
 528     },
 529     function(err, results) {
 530         // results is now equal to: {one: 1, two: 2}
 531     });
 532
 533
 534 ---------------------------------------
 535
 536 <a name="parallel" />
 537 ### parallel(tasks, [callback])
 538
 539 Run an array of functions in parallel, without waiting until the previous
 540 function has completed. If any of the functions pass an error to its
 541 callback, the main callback is immediately called with the value of the error.
 542 Once the tasks have completed, the results are passed to the final callback as an
 543 array.
 544
 545 It is also possible to use an object instead of an array. Each property will be
 546 run as a function and the results will be passed to the final callback as an object
 547 instead of an array. This can be a more readable way of handling results from
 548 async.parallel.
 549
 550
 551 __Arguments__
 552
 553 * tasks - An array or object containing functions to run, each function is passed a
 554   callback it must call on completion.
 555 * callback(err, results) - An optional callback to run once all the functions
 556   have completed. This function gets an array of all the arguments passed to
 557   the callbacks used in the array.
 558
 559 __Example__
 560
 561     async.parallel([
 562         function(callback){
 563             setTimeout(function(){
 564                 callback(null, 'one');
 565             }, 200);
 566         },
 567         function(callback){
 568             setTimeout(function(){
 569                 callback(null, 'two');
 570             }, 100);
 571         },
 572     ],
 573     // optional callback
 574     function(err, results){
 575         // the results array will equal ['one','two'] even though
 576         // the second function had a shorter timeout.
 577     });
 578
 579
 580     // an example using an object instead of an array
 581     async.parallel({
 582         one: function(callback){
 583             setTimeout(function(){
 584                 callback(null, 1);
 585             }, 200);
 586         },
 587         two: function(callback){
 588             setTimeout(function(){
 589                 callback(null, 2);
 590             }, 100);
 591         },
 592     },
 593     function(err, results) {
 594         // results is now equals to: {one: 1, two: 2}
 595     });
 596
 597
 598 ---------------------------------------
 599
 600 <a name="whilst" />
 601 ### whilst(test, fn, callback)
 602
 603 Repeatedly call fn, while test returns true. Calls the callback when stopped,
 604 or an error occurs.
 605
 606 __Arguments__
 607
 608 * test() - synchronous truth test to perform before each execution of fn.
 609 * fn(callback) - A function to call each time the test passes. The function is
 610   passed a callback which must be called once it has completed with an optional
 611   error as the first argument.
 612 * callback(err) - A callback which is called after the test fails and repeated
 613   execution of fn has stopped.
 614
 615 __Example__
 616
 617     var count = 0;
 618
 619     async.whilst(
 620         function () { return count < 5; },
 621         function (callback) {
 622             count++;
 623             setTimeout(callback, 1000);
 624         },
 625         function (err) {
 626             // 5 seconds have passed
 627         }
 628     );
 629
 630
 631 ---------------------------------------
 632
 633 <a name="until" />
 634 ### until(test, fn, callback)
 635
 636 Repeatedly call fn, until test returns true. Calls the callback when stopped,
 637 or an error occurs.
 638
 639 The inverse of async.whilst.
 640
 641
 642 ---------------------------------------
 643
 644 <a name="waterfall" />
 645 ### waterfall(tasks, [callback])
 646
 647 Runs an array of functions in series, each passing their results to the next in
 648 the array. However, if any of the functions pass an error to the callback, the
 649 next function is not executed and the main callback is immediately called with
 650 the error.
 651
 652 __Arguments__
 653
 654 * tasks - An array of functions to run, each function is passed a callback it
 655   must call on completion.
 656 * callback(err, [results]) - An optional callback to run once all the functions
 657   have completed. This will be passed the results of the last task's callback.
 658
 659
 660
 661 __Example__
 662
 663     async.waterfall([
 664         function(callback){
 665             callback(null, 'one', 'two');
 666         },
 667         function(arg1, arg2, callback){
 668             callback(null, 'three');
 669         },
 670         function(arg1, callback){
 671             // arg1 now equals 'three'
 672             callback(null, 'done');
 673         }
 674     ], function (err, result) {
 675        // result now equals 'done'
 676     });
 677
 678
 679 ---------------------------------------
 680
 681 <a name="queue" />
 682 ### queue(worker, concurrency)
 683
 684 Creates a queue object with the specified concurrency. Tasks added to the
 685 queue will be processed in parallel (up to the concurrency limit). If all
 686 workers are in progress, the task is queued until one is available. Once
 687 a worker has completed a task, the task's callback is called.
 688
 689 __Arguments__
 690
 691 * worker(task, callback) - An asynchronous function for processing a queued
 692   task.
 693 * concurrency - An integer for determining how many worker functions should be
 694   run in parallel.
 695
 696 __Queue objects__
 697
 698 The queue object returned by this function has the following properties and
 699 methods:
 700
 701 * length() - a function returning the number of items waiting to be processed.
 702 * concurrency - an integer for determining how many worker functions should be
 703   run in parallel. This property can be changed after a queue is created to
 704   alter the concurrency on-the-fly.
 705 * push(task, [callback]) - add a new task to the queue, the callback is called
 706   once the worker has finished processing the task.
 707   instead of a single task, an array of tasks can be submitted. the respective callback is used for every task in the list.
 708 * saturated - a callback that is called when the queue length hits the concurrency and further tasks will be queued
 709 * empty - a callback that is called when the last item from the queue is given to a worker
 710 * drain - a callback that is called when the last item from the queue has returned from the worker
 711
 712 __Example__
 713
 714     // create a queue object with concurrency 2
 715
 716     var q = async.queue(function (task, callback) {
 717         console.log('hello ' + task.name);
 718         callback();
 719     }, 2);
 720
 721
 722     // assign a callback
 723     q.drain = function() {
 724         console.log('all items have been processed');
 725     }
 726
 727     // add some items to the queue
 728
 729     q.push({name: 'foo'}, function (err) {
 730         console.log('finished processing foo');
 731     });
 732     q.push({name: 'bar'}, function (err) {
 733         console.log('finished processing bar');
 734     });
 735
 736     // add some items to the queue (batch-wise)
 737
 738     q.push([{name: 'baz'},{name: 'bay'},{name: 'bax'}], function (err) {
 739         console.log('finished processing bar');
 740     });
 741
 742
 743 ---------------------------------------
 744
 745 <a name="auto" />
 746 ### auto(tasks, [callback])
 747
 748 Determines the best order for running functions based on their requirements.
 749 Each function can optionally depend on other functions being completed first,
 750 and each function is run as soon as its requirements are satisfied. If any of
 751 the functions pass an error to their callback, that function will not complete
 752 (so any other functions depending on it will not run) and the main callback
 753 will be called immediately with the error. Functions also receive an object
 754 containing the results of functions which have completed so far.
 755
 756 __Arguments__
 757
 758 * tasks - An object literal containing named functions or an array of
 759   requirements, with the function itself the last item in the array. The key
 760   used for each function or array is used when specifying requirements. The
 761   syntax is easier to understand by looking at the example.
 762 * callback(err, results) - An optional callback which is called when all the
 763   tasks have been completed. The callback will receive an error as an argument
 764   if any tasks pass an error to their callback. If all tasks complete
 765   successfully, it will receive an object containing their results.
 766
 767 __Example__
 768
 769     async.auto({
 770         get_data: function(callback){
 771             // async code to get some data
 772         },
 773         make_folder: function(callback){
 774             // async code to create a directory to store a file in
 775             // this is run at the same time as getting the data
 776         },
 777         write_file: ['get_data', 'make_folder', function(callback){
 778             // once there is some data and the directory exists,
 779             // write the data to a file in the directory
 780             callback(null, filename);
 781         }],
 782         email_link: ['write_file', function(callback, results){
 783             // once the file is written let's email a link to it...
 784             // results.write_file contains the filename returned by write_file.
 785         }]
 786     });
 787
 788 This is a fairly trivial example, but to do this using the basic parallel and
 789 series functions would look like this:
 790
 791     async.parallel([
 792         function(callback){
 793             // async code to get some data
 794         },
 795         function(callback){
 796             // async code to create a directory to store a file in
 797             // this is run at the same time as getting the data
 798         }
 799     ],
 800     function(results){
 801         async.series([
 802             function(callback){
 803                 // once there is some data and the directory exists,
 804                 // write the data to a file in the directory
 805             },
 806             email_link: function(callback){
 807                 // once the file is written let's email a link to it...
 808             }
 809         ]);
 810     });
 811
 812 For a complicated series of async tasks using the auto function makes adding
 813 new tasks much easier and makes the code more readable.
 814
 815
 816 ---------------------------------------
 817
 818 <a name="iterator" />
 819 ### iterator(tasks)
 820
 821 Creates an iterator function which calls the next function in the array,
 822 returning a continuation to call the next one after that. Its also possible to
 823 'peek' the next iterator by doing iterator.next().
 824
 825 This function is used internally by the async module but can be useful when
 826 you want to manually control the flow of functions in series.
 827
 828 __Arguments__
 829
 830 * tasks - An array of functions to run, each function is passed a callback it
 831   must call on completion.
 832
 833 __Example__
 834
 835     var iterator = async.iterator([
 836         function(){ sys.p('one'); },
 837         function(){ sys.p('two'); },
 838         function(){ sys.p('three'); }
 839     ]);
 840
 841     node> var iterator2 = iterator();
 842     'one'
 843     node> var iterator3 = iterator2();
 844     'two'
 845     node> iterator3();
 846     'three'
 847     node> var nextfn = iterator2.next();
 848     node> nextfn();
 849     'three'
 850
 851
 852 ---------------------------------------
 853
 854 <a name="apply" />
 855 ### apply(function, arguments..)
 856
 857 Creates a continuation function with some arguments already applied, a useful
 858 shorthand when combined with other control flow functions. Any arguments
 859 passed to the returned function are added to the arguments originally passed
 860 to apply.
 861
 862 __Arguments__
 863
 864 * function - The function you want to eventually apply all arguments to.
 865 * arguments... - Any number of arguments to automatically apply when the
 866   continuation is called.
 867
 868 __Example__
 869
 870     // using apply
 871
 872     async.parallel([
 873         async.apply(fs.writeFile, 'testfile1', 'test1'),
 874         async.apply(fs.writeFile, 'testfile2', 'test2'),
 875     ]);
 876
 877
 878     // the same process without using apply
 879
 880     async.parallel([
 881         function(callback){
 882             fs.writeFile('testfile1', 'test1', callback);
 883         },
 884         function(callback){
 885             fs.writeFile('testfile2', 'test2', callback);
 886         },
 887     ]);
 888
 889 It's possible to pass any number of additional arguments when calling the
 890 continuation:
 891
 892     node> var fn = async.apply(sys.puts, 'one');
 893     node> fn('two', 'three');
 894     one
 895     two
 896     three
 897
 898 ---------------------------------------
 899
 900 <a name="nextTick" />
 901 ### nextTick(callback)
 902
 903 Calls the callback on a later loop around the event loop. In node.js this just
 904 calls process.nextTick, in the browser it falls back to setTimeout(callback, 0),
 905 which means other higher priority events may precede the execution of the callback.
 906
 907 This is used internally for browser-compatibility purposes.
 908
 909 __Arguments__
 910
 911 * callback - The function to call on a later loop around the event loop.
 912
 913 __Example__
 914
 915     var call_order = [];
 916     async.nextTick(function(){
 917         call_order.push('two');
 918         // call_order now equals ['one','two]
 919     });
 920     call_order.push('one')
 921
 922
 923 ## Utils
 924
 925 <a name="memoize" />
 926 ### memoize(fn, [hasher])
 927
 928 Caches the results of an async function. When creating a hash to store function
 929 results against, the callback is omitted from the hash and an optional hash
 930 function can be used.
 931
 932 __Arguments__
 933
 934 * fn - the function you to proxy and cache results from.
 935 * hasher - an optional function for generating a custom hash for storing
 936   results, it has all the arguments applied to it apart from the callback, and
 937   must be synchronous.
 938
 939 __Example__
 940
 941     var slow_fn = function (name, callback) {
 942         // do something
 943         callback(null, result);
 944     };
 945     var fn = async.memoize(slow_fn);
 946
 947     // fn can now be used as if it were slow_fn
 948     fn('some name', function () {
 949         // callback
 950     });
 951
 952 <a name="unmemoize" />
 953 ### unmemoize(fn)
 954
 955 Undoes a memoized function, reverting it to the original, unmemoized
 956 form. Comes handy in tests.
 957
 958 __Arguments__
 959
 960 * fn - the memoized function
 961
 962 <a name="log" />
 963 ### log(function, arguments)
 964
 965 Logs the result of an async function to the console. Only works in node.js or
 966 in browsers that support console.log and console.error (such as FF and Chrome).
 967 If multiple arguments are returned from the async function, console.log is
 968 called on each argument in order.
 969
 970 __Arguments__
 971
 972 * function - The function you want to eventually apply all arguments to.
 973 * arguments... - Any number of arguments to apply to the function.
 974
 975 __Example__
 976
 977     var hello = function(name, callback){
 978         setTimeout(function(){
 979             callback(null, 'hello ' + name);
 980         }, 1000);
 981     };
 982
 983     node> async.log(hello, 'world');
 984     'hello world'
 985
 986
 987 ---------------------------------------
 988
 989 <a name="dir" />
 990 ### dir(function, arguments)
 991
 992 Logs the result of an async function to the console using console.dir to
 993 display the properties of the resulting object. Only works in node.js or
 994 in browsers that support console.dir and console.error (such as FF and Chrome).
 995 If multiple arguments are returned from the async function, console.dir is
 996 called on each argument in order.
 997
 998 __Arguments__
 999
1000 * function - The function you want to eventually apply all arguments to.
1001 * arguments... - Any number of arguments to apply to the function.
1002
1003 __Example__
1004
1005     var hello = function(name, callback){
1006         setTimeout(function(){
1007             callback(null, {hello: name});
1008         }, 1000);
1009     };
1010
1011     node> async.dir(hello, 'world');
1012     {hello: 'world'}
1013
1014
1015 ---------------------------------------
1016
1017 <a name="noConflict" />
1018 ### noConflict()
1019
1020 Changes the value of async back to its original value, returning a reference to the
1021 async object.