diff --git a/docs/v3/docs.html b/docs/v3/docs.html index b97c9a17d..244a2f3bf 100644 --- a/docs/v3/docs.html +++ b/docs/v3/docs.html @@ -14603,6 +14603,9 @@
callback is
immediately called with the value of the error. Otherwise, callback
receives an array of results when tasks have completed.
+Note: Calling a task's callback with false cancels the series. The
+remaining tasks and final callback will not run. Use null as the error
+argument to continue after a successful task.
It is also possible to use an object instead of an array. Each property will
be run as a function, and the results will be passed to the final callback
as an object instead of an array. This can be a more readable way of handling
diff --git a/docs/v3/index.html b/docs/v3/index.html
index 43bcf3b3c..34c42c4ff 100644
--- a/docs/v3/index.html
+++ b/docs/v3/index.html
@@ -223,7 +223,7 @@
There are cases where you might want to exit early from async flow, when calling an Async method inside another async function:
function myFunction (args, outerCallback) {
async.waterfall([
@@ -240,7 +240,7 @@ Subtle Memory Leaks
}
Something happened in a waterfall where you want to skip the rest of the execution, so you call an outer callack. However, Async will still wait for that inner next callback to be called, leaving some closure scope allocated.
As of version 3.0, you can call any Async callback with false as the error argument, and the rest of the execution of the Async method will be stopped or ignored.
As of version 3.0, calling any Async callback with false as the error argument cancels the flow: remaining work will be stopped or ignored, and the final callback will not run. Use null instead when a task succeeds and the flow should continue.
function (arg, next) {
if (someImportantCondition()) {
outerCallback(null)
diff --git a/docs/v3/module-ControlFlow.html b/docs/v3/module-ControlFlow.html
index e68627c51..3535efea3 100644
--- a/docs/v3/module-ControlFlow.html
+++ b/docs/v3/module-ControlFlow.html
@@ -4540,6 +4540,9 @@ (static) series
error to its callback, no more functions are run, and callback is
immediately called with the value of the error. Otherwise, callback
receives an array of results when tasks have completed.
+
Note: Calling a task's callback with false cancels the series. The
+remaining tasks and final callback will not run. Use null as the error
+argument to continue after a successful task.
It is also possible to use an object instead of an array. Each property will
be run as a function, and the results will be passed to the final callback
as an object instead of an array. This can be a more readable way of handling
diff --git a/docs/v3/series.js.html b/docs/v3/series.js.html
index 1c429cd75..92d8a659b 100644
--- a/docs/v3/series.js.html
+++ b/docs/v3/series.js.html
@@ -85,6 +85,10 @@
series.js
* immediately called with the value of the error. Otherwise, `callback`
* receives an array of results when `tasks` have completed.
*
+ * **Note:** Calling a task's callback with `false` cancels the series. The
+ * remaining tasks and final `callback` will not run. Use `null` as the error
+ * argument to continue after a successful task.
+ *
* It is also possible to use an object instead of an array. Each property will
* be run as a function, and the results will be passed to the final `callback`
* as an object instead of an array. This can be a more readable way of handling
diff --git a/intro.md b/intro.md
index c8e78b4fc..fe6d3f55a 100644
--- a/intro.md
+++ b/intro.md
@@ -174,7 +174,7 @@ async.map([1, 2, 3], AsyncSquaringLibrary.square.bind(AsyncSquaringLibrary), fun
});
```
-### Subtle Memory Leaks
+### Canceling an async flow
There are cases where you might want to exit early from async flow, when calling an Async method inside another async function:
@@ -196,7 +196,7 @@ function myFunction (args, outerCallback) {
Something happened in a waterfall where you want to skip the rest of the execution, so you call an outer callack. However, Async will still wait for that inner `next` callback to be called, leaving some closure scope allocated.
-As of version 3.0, you can call any Async callback with `false` as the `error` argument, and the rest of the execution of the Async method will be stopped or ignored.
+As of version 3.0, calling any Async callback with `false` as the `error` argument cancels the flow: remaining work will be stopped or ignored, and the final callback will not run. Use `null` instead when a task succeeds and the flow should continue.
```javascript
function (arg, next) {
diff --git a/lib/series.js b/lib/series.js
index 7518e6212..69c2928f5 100644
--- a/lib/series.js
+++ b/lib/series.js
@@ -8,6 +8,10 @@ import eachOfSeries from './eachOfSeries.js'
* immediately called with the value of the error. Otherwise, `callback`
* receives an array of results when `tasks` have completed.
*
+ * **Note:** Calling a task's callback with `false` cancels the series. The
+ * remaining tasks and final `callback` will not run. Use `null` as the error
+ * argument to continue after a successful task.
+ *
* It is also possible to use an object instead of an array. Each property will
* be run as a function, and the results will be passed to the final `callback`
* as an object instead of an array. This can be a more readable way of handling