lib/runner.dart

// Copyright (c) 2015, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

/**
 * A [Runner] runs a function, potentially in a different scope
 * or even isolate.
 */
library dart.pkg.isolate.runner;

import "dart:async" show Future;

/**
 * Calls a function with an argument.
 *
 * The function can be run in a different place from where the `Runner`
 * resides, e.g., in a different isolate.
 */
class Runner {
  /**
   * Request that [function] be called with the provided arguments.
   *
   * The arguments will be applied to the function in the same way as by
   * [Function.apply], but it may happen in a diffent isolate or setting.
   *
   * It's necessary that the function can be sent through a [SendPort]
   * if the call is performed in another isolate.
   * That means the other isolate should be created using [Isolate.spawn]
   * so that it is running the same code as the sending isoalte,
   * and the function must be a static or top-level function.
   *
   * Waits for the result of the call, and completes the returned future
   * with the result, whether it's a value or an error.
   *
   * If the returned future does not complete before `timeLimit` has passed,
   * the [onTimeout] action is executed instead, and its result (whether it
   * returns or throws) is used as the result of the returned future.
   *
   * If `onTimeout` is omitted, a timeout will cause the returned future to
   * complete with a [TimeoutException].
   *
   * The default implementation runs the function in the current isolate.
   */
  Future run(function(argument), Object argument,
             {Duration timeout, onTimeout()}) {
    Future result = new Future.sync(() => function(argument));
    if (timeout != null) {
      result = result.timeout(timeout, onTimeout: onTimeout);
    }
    return result;
  }

  /**
   * Stop the runner.
   *
   * If the runner has allocated resources, e.g., an isolate, it should
   * be released. No further calls to [run] should be made after calling
   * stop.
   */
  Future close() => new Future.value();
}