title: gulp: where is the gulp task callback function defined?
body: <p>A task in gulp can be defined like so:</p>
  
  <pre><code>gulp.task('foobar', function(callback) { ... });
  </code></pre>
  
  <p>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?</p>
  
  <p><a href="https://github.com/gulpjs/gulp/blob/master/docs/API.md#accept-a-callback">These docs</a> 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.</p>
  
  <p>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:</p>
  
  <pre><code>gulp.task('foobar', function(callback) {
      callback();
  });
  
  gulp.task('bazkad', function(callback) {
      callback("some string");
  });  
  </code></pre>
  
  <p>(aside: how do I place a break between code blocks in StackOverflow markdown?)</p>
  
  <pre><code>$ 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.&lt;anonymous&gt; (~\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.&lt;anonymous&gt; (~\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)
  </code></pre>
  
  <p>So, questions I have are:</p>
  
  <ul>
  <li>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?</li>
  <li>Could I override it with some other function (and would there be any sane reason to do so)?</li>
  </ul>
  
  <p>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.</p>
  
  <p>Thanks for any help.</p>