Refactor, rename, and generally rationalize code in the Frog isolates library,

lib/isolate/frog/isolateimpl.dart

 // Copyright (c) 2012, 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.
 
 /**
+ * Concepts used here:
+ *
+ * "manager" - A manager contains one or more isolates, schedules their
+ * execution, and performs other plumbing on their behalf.  The isolate
+ * present at the creation of the manager is designated as its "root isolate".
+ * A manager may, for example, be implemented on a web Worker.
+ *
+ * [_Manager] - State present within a manager (exactly once, as a global).
+ *
+ * [_ManagerStub] - A handle held within one manager that allows interaction
+ * with another manager.  A target manager may be addressed by zero or more
+ * [_ManagerStub]s.
+ *
+ */
+
+/**
  * A native object that is shared across isolates. This object is visible to all
- * isolates running on the same worker (either UI or background web worker).
+ * isolates running under the same manager (either UI or background web worker).
  *
  * This is code that is intended to 'escape' the isolate boundaries in order to
  * implement the semantics of isolates in JavaScript. Without this we would have
  * been forced to implement more code (including the top-level event loop) in
  * JavaScript itself.
  */
-_GlobalState get _globalState() native "return \$globalState;";
-set _globalState(_GlobalState val) native "\$globalState = val;";
+_Manager get _globalState() native "return \$globalState;";

[Siggi Cherem (dart-lang), 2012/03/24 00:31:58]

let's add a TODO to move 'manager' to be entirely done in JS (incorporating the
feedback we get from Florian)

[eub, 2012/03/29 00:07:52]

Done.

+set _globalState(_Manager val) native "\$globalState = val;";
 
 void _fillStatics(context) native @"""
   $globals = context.isolateStatics;
   $static_init();
 """;
 
 ReceivePort _port;
 
 SendPort _spawnFunction(void topLevelFunction()) {
   final name = _IsolateNatives._getJSFunctionName(topLevelFunction);
   if (name == null) {
     throw new UnsupportedOperationException(
         "only top-level functions can be spawned.");
   }
   return _IsolateNatives._spawn2(name, null, false);
 }
 
 SendPort _spawnUri(String uri) {
   return _IsolateNatives._spawn2(null, uri, false);
 }
 
-/** Global state associated with the current worker. See [globalState]. */
+/** State associated with the current manager. See [globalState]. */
 // TODO(sigmund): split in multiple classes: global, thread, main-worker states?
-class _GlobalState {
+class _Manager {
 
-  /** Next available isolate id. */
+  /** Next available isolate id within this [_Manager]. */
   int nextIsolateId = 0;
 
-  /** Worker id associated with this worker. */
-  int currentWorkerId = 0;
+  /** id assigned to this [_Manager]. */
+  int currentManagerId = 0;
 
   /**
-   * Next available worker id. Only used by the main worker to assign a unique
-   * id to each worker created by it.
+   * Next available manager id. Only used by the main manager to assign a unique
+   * id to each manager created by it.
    */
-  int nextWorkerId = 1;
+  int nextManagerId = 1;
 
   /** Context for the currently running [Isolate]. */
   _IsolateContext currentContext = null;
 
-  /** Context for the root [Isolate] that first run in this worker. */
+  /** Context for the root [Isolate] that first run in this [_Manager]. */
   _IsolateContext rootContext = null;
 
   /** The top-level event loop. */
   _EventLoop topEventLoop;
 
-  /** Whether this program is running in a background worker. */
+  /** Whether this program is running from the command line. */
+  bool fromCommandLine;
+
+  /** Whether this [_Manager] is running as a web worker. */
   bool isWorker;
 
-  /** Whether this program is running in a UI worker. */
-  bool inWindow;
-
-  /** Whether we support spawning workers. */
+  /** Whether we support spawning web workers. */
   bool supportsWorkers;
 
   /**
    * Whether to use web workers when implementing isolates. Set to false for
    * debugging/testing.
    */
   bool get useWorkers() => supportsWorkers;
 
   /**
    * Whether to use the web-worker JSON-based message serialization protocol. By
    * default this is only used with web workers. For debugging, you can force
    * using this protocol by changing this field value to [true].
    */
   bool get needSerialization() => useWorkers;
 
   /**
    * Registry of isolates. Isolates must be registered if, and only if, receive
    * ports are alive.  Normally no open receive-ports means that the isolate is
    * dead, but DOM callbacks could resurrect it.
    */
   Map<int, _IsolateContext> isolates;
 
-  /** Reference to the main worker. */
-  _MainWorker mainWorker;
+  /** Reference to the main [_Manager].  Null in the main [_Manager] itself. */
+  _ManagerStub mainManager;
 
-  /** Registry of active workers. Only used in the main worker. */
-  Map<int, Dynamic> workers;
+  /** Registry of active [_ManagerStub]s.  Only used in the main [_Manager]. */
+  Map<int, _ManagerStub> managers;
 
-  _GlobalState() {
+  _Manager() {
     topEventLoop = new _EventLoop();
     isolates = {};
-    workers = {};
-    mainWorker = new _MainWorker();
+    managers = {};
+    mainManager = new _MainManagerStub();
     _nativeInit();
   }
 
   void _nativeInit() native @"""
     this.isWorker = typeof ($globalThis['importScripts']) != 'undefined';
-    this.inWindow = typeof(window) !== 'undefined';
+    this.fromCommandLine = typeof(window) == 'undefined';
     this.supportsWorkers = this.isWorker ||
         ((typeof $globalThis['Worker']) != 'undefined');
     if (this.isWorker) {
       $globalThis.onmessage = function (e) {
-        _IsolateNatives._processWorkerMessage(this.mainWorker, e);
+        _IsolateNatives._processWorkerMessage(this.mainManager, e);
       };
     }
   """ {
     // Declare that the native code has a dependency on this fn.
     _IsolateNatives._processWorkerMessage(null, null);
   }
 
   /**
-   * Close the worker running this code, called when there is nothing else to
-   * run.
+   * Close the worker running this code if all isolates are done.

[Siggi Cherem (dart-lang), 2012/03/24 00:31:58]

nit: this might fit in a single line comment.

[eub, 2012/03/29 00:07:52]

Done.

    */
-  void closeWorker() {
-    if (isWorker) {
-      if (!isolates.isEmpty()) return;
-      mainWorker.postMessage(
-          _serializeMessage({'command': 'close'}));
-    } else if (isolates.containsKey(rootContext.id) && workers.isEmpty() &&
-               !supportsWorkers && !inWindow) {
-      // This should only trigger when running on the command-line.
-      // We don't want this check to execute in the browser where the isolate
-      // might still be alive due to DOM callbacks.
-      throw new Exception("Program exited with open ReceivePorts.");
+  void maybeCloseWorker() {
+    if (isolates.isEmpty()) {
+      mainManager.postMessage(_serializeMessage({'command': 'close'}));
     }
   }
 }
 
 /** Context information tracked for each isolate. */
 class _IsolateContext {
   /** Current isolate id. */
   int id;
 
   /** Registry of receive ports currently active on this isolate. */
@@ skipping 75 matching lines @@
 
   _IsolateEvent dequeue() {
     if (events.isEmpty()) return null;
     return events.removeFirst();
   }
 
   /** Process a single event, if any. */
   bool runIteration() {
     final event = dequeue();
     if (event == null) {
-      _globalState.closeWorker();
+      if (_globalState.isWorker) {
+        _globalState.maybeCloseWorker();
+      } else if (_globalState.rootContext != null &&
+                 _globalState.isolates.containsKey(
+                     _globalState.rootContext.id) &&
+                 _globalState.fromCommandLine &&
+                 _globalState.rootContext.ports.isEmpty()) {
+        // We want to reach here only on the main [_Manager] and
+        // only on the command-line.  In the browser where the isolate

[Siggi Cherem (dart-lang), 2012/03/24 00:31:58]

I had a hard time understanding the second sentence, maybe split it in 2? maybe
remove the word 'where'?

[eub, 2012/03/29 00:07:52]

Yeah, I don't know what the 'where' was doing in there.

+        // might still be alive due to DOM callbacks, but the
+        // presumption is that on the command-line, no future events
+        // can be injected into the event queue once it's empty.  Node
+        // has setTimeout so this presumption is incorrect there.  We
+        // think(?) that in d8 this assumption is valid.
+        throw new Exception("Program exited with open ReceivePorts.");
+      }
       return false;
     }
     event.process();
     return true;
   }
 
   /**
    * Runs multiple iterations of the run-loop. If possible, each iteration is
    * run asynchronously.
    */
@@ skipping 15 matching lines @@
    * Call [_runHelper] but ensure that worker exceptions are propragated. Note
    * this is called from JavaScript (see $wrap_call in corejs.dart).
    */
   void run() {
     if (!_globalState.isWorker) {
       _runHelper();
     } else {
       try {
         _runHelper();
       } catch(var e, var trace) {
-        _globalState.mainWorker.postMessage(_serializeMessage(
+        _globalState.mainManager.postMessage(_serializeMessage(
             {'command': 'error', 'msg': '$e\n$trace' }));
       }
     }
   }
 }
 
 /** An event in the top-level event queue. */
 class _IsolateEvent {
   _IsolateContext isolate;
   Function fn;
   String message;
 
   _IsolateEvent(this.isolate, this.fn, this.message);
 
   void process() {
     isolate.eval(fn);
   }
 }
 
+/** An interface for a stub used to interact with a manager. */
+interface _ManagerStub {
+  get id();
+  void set id(int i);
+  void set onmessage(Function f);
+  void postMessage(msg);
+  void terminate();
+}
 
-/** Default worker. */
-class _MainWorker {
-  int id = 0;
+/** A stub for interacting with the main manager. */
+class _MainManagerStub implements _ManagerStub {
+  get id() => 0;
+  void set id(int i) { throw new NotImplementedException(); }
   void postMessage(msg) native @"$globalThis.postMessage(msg);";
-  void terminate() {}
+  void terminate() {}  // Nothing useful to do here.
 }
 
 /**
- * A web worker. This type is also defined in 'dart:dom', but we define it here
- * to avoid introducing a dependency from corelib to dom. This definition uses a
+ * A stub for interacting with a manager built on a web worker. The type
+ * Worker is also defined in 'dart:dom', but we define it here to avoid
+ * introducing a dependency from corelib to dom. This definition uses a
  * 'hidden' type (* prefix on the native name) to enforce that the type is
  * defined dynamically only when web workers are actually available.
  */
-class _Worker native "*Worker" {
+class _WorkerStub implements _ManagerStub native "*Worker" {
   get id() native "return this.id;";
   void set id(i) native "this.id = i;";
   void set onmessage(f) native "this.onmessage = f;";
   void postMessage(msg) native "return this.postMessage(msg);";
+  // terminate() is implemented by Worker.

[Siggi Cherem (dart-lang), 2012/03/24 00:31:58]

don't we need it in the same way as we did with the previous functions? e.g:
void terminate() native "this.terminate();";

[eub, 2012/03/29 00:07:52]

Apparently not, as discussed.

 }
 
 final String _SPAWNED_SIGNAL = "spawned";
 
 class _IsolateNatives {
 
   /** JavaScript-specific implementation to spawn an isolate. */
   static Future<SendPort> spawn(Isolate isolate, bool isLight) {
     Completer<SendPort> completer = new Completer<SendPort>();
     ReceivePort port = new ReceivePort();
@@ skipping 10 matching lines @@
     } else {
       _startNonWorker(isolate, port.toSendPort());
     }
 
     return completer.future;
   }
 
   static SendPort _startWorker(Isolate runnable, SendPort replyPort) {
     var factoryName = _getJSConstructorName(runnable);
     if (_globalState.isWorker) {
-      _globalState.mainWorker.postMessage(_serializeMessage({
+      _globalState.mainManager.postMessage(_serializeMessage({
           'command': 'spawn-worker',
           'factoryName': factoryName,
           'replyPort': _serializeMessage(replyPort)}));
     } else {
       _spawnWorker(factoryName, _serializeMessage(replyPort));
     }
   }
 
   /**
    * The src url for the script tag that loaded this code. Used to create
@@ skipping 22 matching lines @@
     var src = script && script.src;
     if (!src) {
       // TODO()
       src = "FIXME:5407062" + "_" + Math.random().toString();
       if (script) script.src = src;
     }
     return src;
   """;
 
   /** Starts a new worker with the given URL. */
-  static _Worker _newWorker(url) native "return new Worker(url);";
+  static _WorkerStub _newWorker(url) native "return new Worker(url);";
 
   /**
    * Spawns an isolate in a worker. [factoryName] is the Javascript constructor
    * name for the isolate entry point class.
    */
   static void _spawnWorker(factoryName, serializedReplyPort) {
     final worker = _newWorker(_thisScript);
     worker.onmessage = (e) { _processWorkerMessage(worker, e); };
-    var workerId = _globalState.nextWorkerId++;
+    var workerId = _globalState.nextManagerId++;
     // We also store the id on the worker itself so that we can unregister it.
     worker.id = workerId;
-    _globalState.workers[workerId] = worker;
+    _globalState.managers[workerId] = worker;
     worker.postMessage(_serializeMessage({
       'command': 'start',
       'id': workerId,
       'replyTo': serializedReplyPort,
       'factoryName': factoryName }));
   }
 
   /**
    * Assume that [e] is a browser message event and extract its message data.
    * We don't import the dom explicitly so, when workers are disabled, this
    * library can also run on top of nodejs.
    */
   static _getEventData(e) native "return e.data";
 
   /**
    * Process messages on a worker, either to control the worker instance or to
    * pass messages along to the isolate running in the worker.
    */
   static void _processWorkerMessage(sender, e) {
     var msg = _deserializeMessage(_getEventData(e));
     switch (msg['command']) {
       // TODO(sigmund): delete after we migrate to the new API
       case 'start':
-        _globalState.currentWorkerId = msg['id'];
+        _globalState.currentManagerId = msg['id'];
         var runnerObject =
             _allocate(_getJSConstructorFromName(msg['factoryName']));
         var serializedReplyTo = msg['replyTo'];
         _globalState.topEventLoop.enqueue(new _IsolateContext(), function() {
           var replyTo = _deserializeMessage(serializedReplyTo);
           _startIsolate(runnerObject, replyTo);
         }, 'worker-start');
         _globalState.topEventLoop.run();
         break;
       case 'start2':
-        _globalState.currentWorkerId = msg['id'];
+        _globalState.currentManagerId = msg['id'];
         Function entryPoint = _getJSFunctionFromName(msg['functionName']);
         var replyTo = _deserializeMessage(msg['replyTo']);
         _globalState.topEventLoop.enqueue(new _IsolateContext(), function() {
           _startIsolate2(entryPoint, replyTo);
         }, 'worker-start');
         _globalState.topEventLoop.run();
         break;
       // TODO(sigmund): delete after we migrate to the new API
       case 'spawn-worker':
         _spawnWorker(msg['factoryName'], msg['replyPort']);
         break;
       case 'spawn-worker2':
         _spawnWorker2(msg['functionName'], msg['uri'], msg['replyPort']);
         break;
       case 'message':
         msg['port'].send(msg['msg'], msg['replyTo']);
         _globalState.topEventLoop.run();
         break;
       case 'close':
         _log("Closing Worker");
-        _globalState.workers.remove(sender.id);
+        _globalState.managers.remove(sender.id);
         sender.terminate();
         _globalState.topEventLoop.run();
         break;
       case 'log':
         _log(msg['msg']);
         break;
       case 'print':
         if (_globalState.isWorker) {
-          _globalState.mainWorker.postMessage(
+          _globalState.mainManager.postMessage(
               _serializeMessage({'command': 'print', 'msg': msg}));
         } else {
           print(msg['msg']);
         }
         break;
       case 'error':
         throw msg['msg'];
     }
   }
 
-  /** Log a message, forwarding to the main worker if appropriate. */
+  /** Log a message, forwarding to the main [_Manager] if appropriate. */
   static _log(msg) {
     if (_globalState.isWorker) {
-      _globalState.mainWorker.postMessage(
+      _globalState.mainManager.postMessage(
           _serializeMessage({'command': 'log', 'msg': msg }));
     } else {
       try {
         _consoleLog(msg);
       } catch(e, trace) {
         throw new Exception(trace);
       }
     }
   }
 
@@ skipping 96 matching lines @@
     } else {
       _startNonWorker2(functionName, uri, signalReply);
     }
     return new _BufferingSendPort(
         _globalState.currentContext.id, completer.future);
   }
 
   static SendPort _startWorker2(
       String functionName, String uri, SendPort replyPort) {
     if (_globalState.isWorker) {
-      _globalState.mainWorker.postMessage(_serializeMessage({
+      _globalState.mainManager.postMessage(_serializeMessage({
           'command': 'spawn-worker2',
           'functionName': functionName,
           'uri': uri,
           'replyPort': replyPort}));
     } else {
       _spawnWorker2(functionName, uri, replyPort);
     }
   }
 
   static SendPort _startNonWorker2(
@@ skipping 22 matching lines @@
     if (functionName == null) functionName = 'main';
     if (uri == null) uri = _thisScript;
     if (!(new Uri.fromString(uri).isAbsolute())) {
       // The constructor of dom workers requires an absolute URL. If we use a
       // relative path we will get a DOM exception.
       String prefix = _thisScript.substring(0, _thisScript.lastIndexOf('/'));
       uri = "$prefix/$uri";
     }
     final worker = _newWorker(uri);
     worker.onmessage = (e) { _processWorkerMessage(worker, e); };
-    var workerId = _globalState.nextWorkerId++;
+    var workerId = _globalState.nextManagerId++;
     // We also store the id on the worker itself so that we can unregister it.
     worker.id = workerId;
-    _globalState.workers[workerId] = worker;
+    _globalState.managers[workerId] = worker;
     worker.postMessage(_serializeMessage({
       'command': 'start2',
       'id': workerId,
       // Note: we serialize replyPort twice because the child worker needs to
       // first deserialize the worker id, before it can correctly deserialize
       // the port (port deserialization is sensitive to what is the current
       // workerId).
       'replyTo': _serializeMessage(replyPort),
       'functionName': functionName }));
   }
 }