gulp: where is the gulp task callback function defined?

Question

A task in gulp can be defined like so:

gulp.task('foobar', function(callback) { ... });

I'm trying to understand what the callback function is. Where is it defined? Can I pass in some other function as an argument at runtime? What does it do?

These docs indicate that the callback argument is a hint to Orchestrator that the task should be run asynchronously, where the executing the callback indicates that the async task has completed.

With some experimentation it looks like calling the callback with no arguments returns a success state, and calling it with some string throws an error:

gulp.task('foobar', function(callback) {
    callback();
});

gulp.task('bazkad', function(callback) {
    callback("some string");
});  

(aside: how do I place a break between code blocks in StackOverflow markdown?)

$ gulp foobar
[09:59:54] Using gulpfile ~\repos\gulpproj\gulpfile.js
[09:59:54] Starting 'foobar'...
[09:59:54] Finished 'foobar' after 56 μs
$ gulp bazkad
[10:05:49] Using gulpfile ~\repos\gulpproj\gulpfile.js
[10:05:49] Starting 'bazkad'...
[10:05:49] 'bazkad' errored after 55 μs
[10:05:49] Error: some string
    at formatError (~\AppData\Roaming\npm\node_modules\gulp\bin\gulp.js:169:10)
    at Gulp.<anonymous> (~\AppData\Roaming\npm\node_modules\gulp\bin\gulp.js:195:15)
    at Gulp.emit (events.js:107:17)
    at Gulp.Orchestrator._emitTaskDone (~\repos\gulpproj\node_modules\gulp\node_modules\orchestrator\index.js:264:8)
    at ~\repos\gulpproj\node_modules\gulp\node_modules\orchestrator\index.js:275:23
    at finish (~\repos\gulpproj\node_modules\gulp\node_modules\orchestrator\lib\runTask.js:21:8)
    at cb (~\repos\gulpproj\node_modules\gulp\node_modules\orchestrator\lib\runTask.js:29:3)
    at Gulp.<anonymous> (~\repos\gulpproj\gulpfile.js:35:5)
    at module.exports (~\repos\gulpproj\node_modules\gulp\node_modules\orchestrator\lib\runTask.js:34:7)
    at Gulp.Orchestrator._runTask (~\repos\gulpproj\node_modules\gulp\node_modules\orchestrator\index.js:273:3)

So, questions I have are:

• Is this the only functionality of the callback, to raise an exception if passed an argument and to complete successfully otherwise, or does it do something else?
• Could I override it with some other function (and would there be any sane reason to do so)?

Maybe my documentation reading skills are failing me (wouldn't be the first time), but I can't seem to find the answers to these questions in the API docs.

Thanks for any help.

Answer 1

The callback function comes from Orchestrator (or the new one -- undertaker -- in Gulp 4) and is actually nothing more than a call to tell the task system that your task is "done". That's why they changed it to

gulp.task('something', function(done) { ... });

In the upcoming docs to make that point clearer.

Why do you need the callback? Usually, you return a stream when defining a task:

gulp.task('goodstuff', function() {
    return gulp.src('./app/**/*.*')
        .pipe(someotherstuff())
        .pipe(gulp.dest('./dist');
});

By returning a stream, the task system is able to plan the execution of those streams. But sometimes, especially when you're in callback hell or calling some streamless plugin, you aren't able to return a stream. That's what the callback is for. To let the task system know that you're finished and to move on to the next call in the execution chain.

To your questions:

Is this the only functionality of the callback, to raise an exception if passed an argument and to complete successfully otherwise?

No, the only functionality is to let the task system know that your task is done.

Is there anything else that it does?

No.

Could I override it with some other function (and would there be any sane reason to do so)?

No and No.

Is it possible to pass any other arguments to a gulp task function?

No, but why would you? You have the full scope of a JS file on your service, just place your arguments somewhere around.