Add IsolateRunner as a helper around Isolate.

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();
+}