[Pkg-javascript-commits] [node-async] 16/480: added README.md
Jonas Smedegaard
js at moszumanska.debian.org
Fri May 2 08:58:07 UTC 2014
This is an automated email from the git hooks/post-receive script.
js pushed a commit to branch master
in repository node-async.
commit b9a14fd133ab3c1da2fc28c018ddd5aac248183b
Author: Caolan McMahon <caolan at caolanmcmahon.com>
Date: Thu May 27 18:14:36 2010 +0100
added README.md
---
README.md | 223 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 223 insertions(+)
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e868bf1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,223 @@
+# Async
+_Commonly used patterns for asynchronous code in node.js_
+
+Writing an async library has become a bit of a right of passage for node.js
+developers. There are already lots of interesting ideas out there and I
+don't want to add to this myriad of already great modules. Really. Its just
+that I like my Javascript to look like Javascript, and when I'm using node.js,
+I want to stay fairly close to the vanilla async implementation.
+
+Because of this, I've avoided using the exising async wrapper modules in favour
+of the standard callbacks provided by node. However, I've found myself
+repeating a number of patterns, so I've decided to abstract some of the more
+common ones into a separate module. __This is not an attempt to replace the
+standard callback mechanism in node.js.__ Its just some utility functions for
+writing async code, sticking as closely as possible the node's normal
+callbacks. The aim is to play nicely with node's existing async functions, and
+provide some higher-order functions that work when writing async code.
+
+
+## Collections
+
+Not yet documented.
+
+
+## Flow Control
+
+### series(tasks, [callback])
+
+Run an array of functions in series, each one running once the previous
+function has completed. If any functions in the series pass an error to its
+callback, no more functions are run and the callback for the series is
+immediately called with the value of the error.
+
+__Arguments__
+
+* tasks - An array of functions to run, each function is passed a callback it
+ must call on completion.
+* callback(err, results) - An optional callback to run once all the functions
+ have completed. This function gets an array of all the arguments passed to
+ the callbacks used in the array.
+
+__Example__
+
+ async.series([
+ function(callback){
+ // do some stuff ...
+ callback(null, 'one');
+ },
+ function(callback){
+ // do some more stuff ...
+ callback(null, 'two');
+ },
+ ],
+ // optional callback
+ function(err, results){
+ // results is now equal to ['one', 'two']
+ });
+
+
+### parallel(tasks, [callback])
+
+Run an array of functions in parallel, without waiting until the previous
+function has completed. If any of the functions pass an error to its
+callback, the main callback is immediately called with the value of the error.
+
+__Arguments__
+
+* tasks - An array of functions to run, each function is passed a callback it
+ must call on completion.
+* callback(err, results) - An optional callback to run once all the functions
+ have completed. This function gets an array of all the arguments passed to
+ the callbacks used in the array.
+
+__Example__
+
+ async.parallel([
+ function(callback){
+ setTimeout(function(){
+ callback(null, 'one');
+ }, 200);
+ },
+ function(callback){
+ setTimeout(function(){
+ callback(null, 'two');
+ }, 100);
+ },
+ ],
+ // optional callback
+ function(err, results){
+ // in this case, the results array will equal ['two','one']
+ // because the functions were run in parallel and the second
+ // function had a shorter timeout before calling the callback.
+ });
+
+
+### waterfall(tasks, [callback])
+
+Runs an array of functions in series, each passing their results to the next in
+the array. However, if any of the functions pass an error to the callback, the
+next function is not executed and the main callback is immediately called with
+the error.
+
+__Arguments__
+
+* tasks - An array of functions to run, each function is passed a callback it
+ must call on completion.
+* callback(err) - An optional callback to run once all the functions have
+ completed. This function gets passed any error that may have occurred.
+
+__Example__
+
+ async.waterfall([
+ function(callback){
+ callback(null, 'one', 'two');
+ }
+ function(arg1, arg2, callback){
+ callback(null, 'three');
+ }
+ function(arg1, callback){
+ // arg1 now equals 'three'
+ callback(null, 'done');
+ }
+ ]);
+
+
+### auto(tasks, [callback])
+
+Determines the best order for running functions based on their requirements.
+Each function can optionally depend on other functions being completed first,
+and each function is run as soon as its requirements are satisfied. If any of
+the functions pass and error to their callback, that function will not complete
+(so any other functions depending on it will not run) and the main callback
+will be called immediately with the error.
+
+__Arguments__
+
+* tasks - An object literal containing named functions or an array of
+ requirements, with the function itself the last item in the array. The key
+ used for each function or array is used when specifying requirements. The
+ sytax is easier to understand by looking at the example.
+* callback(err) - An optional callback which is called when all the tasks have
+ been completed. The callback may recieve an error as an argument.
+
+__Example__
+
+ async.auto({
+ get_data: function(callback){
+ // async code to get some data
+ },
+ make_folder: function(callback){
+ // async code to create a directory to store a file in
+ // this is run at the same time as getting the data
+ },
+ write_file: ['get_data', 'make_folder', function(callback){
+ // once there is some data and the directory exists,
+ // write the data to a file in the directory
+ },
+ email_link: ['write_file', function(callback){
+ // once the file is written let's email a link to it...
+ }
+ });
+
+This is a fairly trivial example, but to do this using the basic parallel and
+series functions would look like this:
+
+ async.parallel([
+ function(callback){
+ // async code to get some data
+ },
+ function(callback){
+ // async code to create a directory to store a file in
+ // this is run at the same time as getting the data
+ }
+ ],
+ function(results){
+ async.series([
+ function(callback){
+ // once there is some data and the directory exists,
+ // write the data to a file in the directory
+ },
+ email_link: ['write_file', function(callback){
+ // once the file is written let's email a link to it...
+ }
+ ]);
+ });
+
+For a complicated series of async tasks using the auto function makes adding
+new tasks much easier and makes the code more readable.
+
+
+### iterator(tasks)
+
+Creates an iterator function which calls the next function in the array,
+returning a continuation to call the next one after that. Its also possible to
+'peek' the next iterator by doing iterator.next().
+
+This function is used internally by the async module but can be useful when
+you want to manually control the flow of functions in series.
+
+__Arguments__
+
+* tasks - An array of functions to run, each function is passed a callback it
+ must call on completion.
+
+__Example__
+
+ var iterator = async.iterator([
+ function(){ sys.p('one'); },
+ function(){ sys.p('two'); },
+ function(){ sys.p('three'); }
+ ]);
+
+ node> var iterator2 = iterator();
+ 'one'
+ node> var iterator3 = iterator2();
+ 'two'
+ node> iterator3();
+ 'three'
+ node> var nextfn = iterator2.next();
+ node> nextfn();
+ 'three'
+
+
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-javascript/node-async.git
More information about the Pkg-javascript-commits
mailing list