Skip to content
Browse files

Doc clarifications. Self-optimizing function for pipeline. Improved u…

…nit tests for pipeline
  • Loading branch information...
1 parent d5be329 commit ff9412bfee697a740bb4811fd9b56e43337a7ba2 @briancavalier briancavalier committed Sep 25, 2012
Showing with 49 additions and 25 deletions.
  1. +17 −3 docs/api.md
  2. +1 −1 parallel.js
  3. +18 −8 pipeline.js
  4. +1 −1 sequence.js
  5. +12 −12 test/pipeline.js
View
20 docs/api.md
@@ -326,10 +326,16 @@ More when/timeout [examples on the wiki](https://github.com/cujojs/when/wiki/whe
# Concurrency
+These modules allow you to execute tasks in series or parallel. Each module takes an Array of task functions (or a *promise* for an Array), executes the tasks, and returns a promise that resolves when all the tasks have completed.
+
## when/sequence
```js
-var resultsPromise = when.sequence(arrayOfTasks, arg1, arg2 /*, ... */);
+var sequence, resultsPromise;
+
+sequence = require('when/sequence');
+
+resultsPromise = sequence(arrayOfTasks, arg1, arg2 /*, ... */);
```
Run an array of tasks in sequence, without overlap. Each task will be called with the arguments passed to `when.sequence()`, and each may return a promise or a value.
@@ -339,7 +345,11 @@ When all tasks have completed, the returned promise will resolve to an array con
## when/pipeline
```js
-var resultsPromise = when.pipeline(arrayOfTasks, arg1, arg2 /*, ... */);
+var pipeline, resultsPromise;
+
+pipeline = require('when/pipeline');
+
+resultsPromise = pipeline(arrayOfTasks, arg1, arg2 /*, ... */);
```
Run an array of tasks in sequence, without overlap, similarly to [when/sequence](#whensequence). The *first task* (e.g. `arrayOfTasks[0]`) will be called with the arguments passed to `when.pipeline()`, and each subsequence task will be called with the result of the previous task.
@@ -351,7 +361,11 @@ When all tasks have completed, the returned promise will resolve to the result o
## when/parallel
```js
-var resultsPromise = when.parallel(arrayOfTasks, arg1, arg2 /*, ... */);
+var parallel, resultsPromise;
+
+parallel = require('when/parallel');
+
+resultsPromise = parallel(arrayOfTasks, arg1, arg2 /*, ... */);
```
Run an array of tasks in "parallel". The tasks are allowed to execute in any order, and may interleave if they are asynchronous.Each task will be called with the arguments passed to `when.parallel()`, and each may return a promise or a value.
View
2 parallel.js
@@ -14,7 +14,7 @@ define(['./when'], function(when) {
/**
* Run array of tasks in parallel
- * @param tasks {Array} array of task functions
+ * @param tasks {Array|Promise} array or promiseForArray of task functions
* @param [args] {*} arguments to be passed to all tasks
* @return {Promise} promise for array containing the
* result of each task in the array position corresponding
View
26 pipeline.js
@@ -17,20 +17,30 @@ define(['./when'], function(when) {
* Run array of tasks in a pipeline where the next
* tasks receives the result of the previous. The first task
* will receive the initialArgs as its argument list.
- * @param tasks {Array} array of task functions
+ * @param tasks {Array|Promise} array or promise for array of task functions
* @param [initialArgs...] {*} arguments to be passed to the first task
* @return {Promise} promise for return value of the final task
*/
return function pipeline(tasks /* initialArgs... */) {
- var initialArgs = Array.prototype.slice.call(arguments, 1);
+ var initialArgs, runTask;
+
+ initialArgs = Array.prototype.slice.call(arguments, 1);
+
+ // Self-optimizing function to run first task with multiple
+ // args using apply, but subsequence tasks via direct invocation
+ runTask = function(task, args) {
+ runTask = function(task, arg) {
+ return task(arg);
+ };
+
+ return task.apply(null, args);
+ };
+
return when.reduce(tasks,
function(args, task) {
- return [task.apply(null, args)];
- }, initialArgs)
- .then(
- function(result) {
- return result[0];
- }
+ return runTask(task, args);
+ },
+ initialArgs
);
};
View
2 sequence.js
@@ -14,7 +14,7 @@ define(['./when'], function(when) {
/**
* Run array of tasks in sequence with no overlap
- * @param tasks {Array} array of task functions
+ * @param tasks {Array|Promise} array or promiseForArray of task functions
* @param [args] {*} arguments to be passed to all tasks
* @return {Promise} promise for an array containing
* the result of each task in the array position corresponding
View
24 test/pipeline.js
@@ -15,40 +15,40 @@ function createTask(y) {
buster.testCase('when/pipeline', {
'should execute tasks in order': function() {
- return pipeline([createTask('b'), createTask('c')], 'a').then(
+ return pipeline([createTask('b'), createTask('c'), createTask('d')], 'a').then(
function(result) {
- assert.equals(result, 'abc');
+ assert.equals(result, 'abcd');
}
);
},
- 'should resolve to initial zeroeth arg when no tasks supplied': function() {
+ 'should resolve to initial args when no tasks supplied': function() {
return pipeline([], 'a', 'b').then(
function(result) {
- assert.equals(result, 'a');
+ assert.equals(result, ['a', 'b']);
}
);
},
- 'should resolve to undefined when no tasks and no args supplied': function() {
+ 'should resolve to empty array when no tasks and no args supplied': function() {
return pipeline([]).then(
function(result) {
- refute.defined(result);
+ assert.equals(result, []);
}
);
},
'should pass args to initial task': function() {
var expected, tasks;
- function verifyArgs() {
- assert.equals(Array.prototype.slice.call(arguments), expected);
- }
-
expected = [1, 2, 3];
- tasks = [verifyArgs];
+ tasks = [this.spy()];
- return pipeline.apply(null, [tasks].concat(expected));
+ return pipeline.apply(null, [tasks].concat(expected)).then(
+ function() {
+ assert.calledOnceWith.apply(assert, tasks.concat(expected));
+ }
+ );
}
});

0 comments on commit ff9412b

Please sign in to comment.
Something went wrong with that request. Please try again.