Add new Dart API call Dart_MakeIsolateRunnable(). This would allow an

runtime/include/dart_api.h

 // 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.
 
 #ifndef INCLUDE_DART_API_H_
 #define INCLUDE_DART_API_H_
 
 /** \mainpage Dart Embedding API Reference
  *
  * Dart is a class-based programming language for creating structured
@@ skipping 528 matching lines @@
 /**
  * Gets the version string for the Dart VM.
  *
  * The version of the Dart VM can be accessed without initializing the VM.
  *
  * \return The version string for the embedded Dart VM.
  */
 DART_EXPORT const char* Dart_VersionString();
 
 /**
+ * An isolate is the unit of concurrency in Dart. Each isolate has
+ * its own memory and thread of control. No state is shared between
+ * isolates. Instead, isolates communicate by message passing.
+ *
+ * Each thread keeps track of its current isolate, which is the
+ * isolate which is ready to execute on the current thread. The
+ * current isolate may be NULL, in which case no isolate is ready to
+ * execute. Most of the Dart apis require there to be a current
+ * isolate in order to function without error. The current isolate is
+ * set by any call to Dart_CreateIsolate or Dart_EnterIsolate.
+ */
+typedef struct _Dart_Isolate* Dart_Isolate;
+
+/**
  * An isolate creation and initialization callback function.
  *
  * This callback, provided by the embedder, is called when the vm
  * needs to create an isolate. The callback should create an isolate
  * by calling Dart_CreateIsolate and load any scripts required for
  * execution.
  *
  * When the function returns false, it is the responsibility of this
  * function to ensure that Dart_ShutdownIsolate has been called if
  * required (for example, if the isolate was created successfully by
  * Dart_CreateIsolate() but the root library fails to load
  * successfully, then the function should call Dart_ShutdownIsolate
  * before returning).
  *
  * When the function returns false, the function should set *error to
  * a malloc-allocated buffer containing a useful error message.  The
  * caller of this function (the vm) will make sure that the buffer is
  * freed.
  *
  * \param script_uri The uri of the script to load.  This uri has been
  *   canonicalized by the library tag handler from the parent isolate.
  *   The callback is responsible for loading this script by a call to
  *   Dart_LoadScript or Dart_LoadScriptFromSnapshot.
  * \param main The name of the main entry point this isolate will
  *   eventually run.  This is provided for advisory purposes only to
  *   improve debugging messages.  The main function is not invoked by
  *   this function.
+ * \param unhandled_exc The name of the function to this isolate will
+ *   call when an unhandled exception is encountered.
  * \param callback_data The callback data which was passed to the
  *   parent isolate when it was created by calling Dart_CreateIsolate().
  * \param error A structure into which the embedder can place a
  *   C string containing an error message in the case of failures.
  *
  * \return The embedder returns false if the creation and

[Anton Muhin, 2013/04/08 15:20:17]

nit: this doc is not correct any more.

[Ivan Posva, 2013/04/09 17:38:55]

Done.

  *   initialization was not successful and true if successful.
  */
-typedef bool (*Dart_IsolateCreateCallback)(const char* script_uri,
-                                           const char* main,
-                                           void* callback_data,
-                                           char** error);
+typedef Dart_Isolate (*Dart_IsolateCreateCallback)(const char* script_uri,
+                                                   const char* main,
+                                                   void* callback_data,
+                                                   char** error);
 
 /**
  * An isolate interrupt callback function.
  *
  * This callback, provided by the embedder, is called when an isolate
  * is interrupted as a result of a call to Dart_InterruptIsolate().
  * When the callback is called, Dart_CurrentIsolate can be used to
  * figure out which isolate is being interrupted.
  *
  * \return The embedder returns true if the isolate should continue
@@ skipping 75 matching lines @@
 DART_EXPORT bool Dart_SetVMFlags(int argc, const char** argv);
 
 /**
  * Returns true if the named VM flag is set.
  */
 DART_EXPORT bool Dart_IsVMFlagSet(const char* flag_name);
 
 // --- Isolates ---
 
 /**
- * An isolate is the unit of concurrency in Dart. Each isolate has
- * its own memory and thread of control. No state is shared between
- * isolates. Instead, isolates communicate by message passing.
- *
- * Each thread keeps track of its current isolate, which is the
- * isolate which is ready to execute on the current thread. The
- * current isolate may be NULL, in which case no isolate is ready to
- * execute. Most of the Dart apis require there to be a current
- * isolate in order to function without error. The current isolate is
- * set by any call to Dart_CreateIsolate or Dart_EnterIsolate.
- */
-typedef struct _Dart_Isolate* Dart_Isolate;
-
-/**
  * Creates a new isolate. The new isolate becomes the current isolate.
  *
  * A snapshot can be used to restore the VM quickly to a saved state
  * and is useful for fast startup. If snapshot data is provided, the
  * isolate will be started using that snapshot data.
  *
  * Requires there to be no current isolate.
  *
  * \param script_uri The name of the script this isolate will load.
  *   Provided only for advisory purposes to improve debugging messages.
@@ skipping 113 matching lines @@
  * 'isolate' does not execute any further Dart code, then the
  * interrupt will not occur at all.  If and when the isolate is
  * interrupted, the isolate interrupt callback will be invoked with
  * 'isolate' as the current isolate (see
  * Dart_IsolateInterruptCallback).
  *
  * \param isolate The isolate to be interrupted.
  */
 DART_EXPORT void Dart_InterruptIsolate(Dart_Isolate isolate);
 
+
+/**
+ * Make isolate runnable.
+ *
+ * When isolates are spawned this function is used to indicate that
+ * the creation and initialization (including script loading) of the
+ * isolate is complete and the isolate can start.
+ * This function does not expect there to be a current isolate.
+ *
+ * \param isolate The isolate to be made runnable.
+ */
+DART_EXPORT bool Dart_IsolateMakeRunnable(Dart_Isolate isolate);

[Anton Muhin, 2013/04/08 15:20:17]

any restriction on thread affinity? 

[Ivan Posva, 2013/04/09 17:38:55]

Not sure I understand the question, but this will tell the VM that the VM
internal thread pool is allowed to pickup the isolate and start dispatching
events. If this call is made from within the Dart_IsolateCreateCallback, then
dispatching starts once the callback returns.

[Anton Muhin, 2013/04/09 17:45:12]

Sorry for not being clear, I was curious if there are any restrictions for the
thread on which I can invoke this method?

Must it be a thread on which the isolate callback has been invoked on any other
thread?

Overall, are there any restrictions on the thread from which I can load the
source of the isolate?

On 2013/04/09 17:38:55, Ivan Posva wrote:

[Ivan Posva, 2013/04/09 18:19:48]

The Dart_IsolateMakeRunnable should be callable on any thread. As the
documentation says, you do not have to enter any isolate to make that call.
To load sources into an isolate you need to enter that isolate on the thread
calling Dart_LoadLibrary and friends. This is only possible once you have exited
the newly created isolate from within the callback.

+
+
 // --- Messages and Ports ---
 
 /**
  * A port is used to send or receive inter-isolate messages
  */
 typedef int64_t Dart_Port;
 
 /**
  * ILLEGAL_PORT is a port number guaranteed never to be associated with a valid
  * port.
@@ skipping 1717 matching lines @@
  *
  * \param object An object.
  * \param peer A value to store in the peer field.
  *
  * \return Returns an error if 'object' is a subtype of Null, num, or
  *   bool.
  */
 DART_EXPORT Dart_Handle Dart_SetPeer(Dart_Handle object, void* peer);
 
 #endif  // INCLUDE_DART_API_H_