- Refactor the isolate callback mechanism to also include creation of the

include/dart_api.h

Index: include/dart_api.h
===================================================================
--- include/dart_api.h	(revision 1818)
+++ include/dart_api.h	(working copy)
@@ -226,25 +226,34 @@
 // --- Initialization and Globals ---
 
 /**
- * An isolate initialization callback function.
+ * A type for passing error messages back when creation and initialization
+ * of isolate fails.
+ * The caller must ensure that 'buffer' points to a buffer whose length is
+ * 'length' and it must also manage the lifetime of this buffer.

[turnidge, 2011/11/28 18:39:58]

Since the caller is usually the VM itself instead of the embedder, consider
changing the two "must"s to "will"s.

[siva, 2011/11/29 00:54:25]

We are passing Dart_ErrorBuffer in Dart_CreateIsolate also now and for this case
the caller is the embedder. Maybe I can word it as "the caller ensures that
'buffer'..." and
"'length' and also manages the lifetime of this buffer'

On 2011/11/28 18:39:58, turnidge wrote:

+ */
+typedef struct {
+  char* buffer;
+  int length;
+} Dart_ErrorBuffer;
+
+/**
+ * An isolate creation and initialization callback function.
  *
- * This callback, provided by the embedder, is called during isolate
- * creation. It is called for all isolates, regardless of whether they
- * are created via Dart_CreateIsolate or directly from Dart code.
+ * This callback, provided by the embedder, is called when an isolate needs
+ * to be created. The callback should create an isolate and load up the

[turnidge, 2011/11/28 18:39:58]

Maybe we can say "load" instead of "load up".

[siva, 2011/11/29 00:54:25]

Done.

+ * required scripts for execution.
  *
- * \param data Embedder-specific data used during isolate initialization.
+ * \param error A structure into which the embedder can place a
+ *   C string containing an error message in the case of failures.
  *
- * \return If the embedder returns NULL, then the isolate being
- *   initialized will be shut down without executing any Dart code.
- *   Otherwise, the embedder should return a pointer to
- *   embedder-specific data created during the initialization of this
- *   isolate. This data will, in turn, be passed by the VM to all
- *   isolates spawned from the isolate currently being initialized.
+ * \return the embedder returns false if the creation and initialization was not
+ *   successful and true if successful. The embedder is responsible for
+ *   maintaining consistency in the case of errors (e.g: isolate is created,
+ *   but loading of scripts fails then the embedder should ensure that
+ *   Dart_ShutdownIsolate is called on the isolate).
  */
-typedef void* (*Dart_IsolateInitCallback)(void* embedder_data);
-// TODO(iposva): Pass a specification of the app file being spawned.
-// TODO(turnidge): We don't actually shut down the isolate on NULL yet.
-// TODO(turnidge): Should we separate the two return values?
+typedef bool (*Dart_IsolateCreateCallback)(void* callback_data,
+                                           Dart_ErrorBuffer error);
 
 /**
  * Initializes the VM with the given commmand line flags.
@@ -252,12 +261,12 @@
  * \param argc The length of the arguments array.
  * \param argv An array of arguments.
  * \param callback A function to be called during isolate creation.
- *   See Dart_IsolateInitCallback.
+ *   See Dart_IsolateCreateCallback.
  *
  * \return True if initialization is successful.
  */
 DART_EXPORT bool Dart_Initialize(int argc, const char** argv,
-                                 Dart_IsolateInitCallback callback);
+                                 Dart_IsolateCreateCallback callback);
 
 /**
  * Returns true if the named VM flag is set.
@@ -296,13 +305,13 @@
  *
  * \param snapshot A buffer containing a VM snapshot or NULL if no
  *   snapshot is provided.
- * \param data Embedder-specific data. See Dart_IsolateInitCallback.
  *
  * \return The new isolate is returned. May be NULL if an error
  *   occurs duing isolate initialization.
  */
 DART_EXPORT Dart_Isolate Dart_CreateIsolate(const Dart_Snapshot* snapshot,
-                                            void* data);
+                                            void* callback_data,
+                                            Dart_ErrorBuffer error);
 // TODO(turnidge): Document behavior when there is already a current
 // isolate.