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

include/dart_api.h

 // Copyright (c) 2011, 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 208 matching lines @@
  *
  * UNIMPLEMENTED.
  *
  * Requires there to be a current isolate.
  */
 DART_EXPORT Dart_Handle Dart_MakePersistentHandle(Dart_Handle object);
 
 // --- 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.
  *
  * \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.
  */
 DART_EXPORT bool Dart_IsVMFlagSet(const char* flag_name);
 
 // --- Isolates ---
 
 /**
  * An isolate is the unit of concurrency in Dart. Each isolate has
@@ skipping 18 matching lines @@
 
 /**
  * Creates a new isolate. If snapshot data is provided, the isolate
  * will be started using that snapshot data. The new isolate becomes
  * the current isolate.
  *
  * Requires there to be no current isolate.
  *
  * \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.
 
 /**
  * Shuts down the current isolate. After this call, the current
  * isolate is NULL.
  *
  * Requires there to be a current isolate.
  */
 DART_EXPORT void Dart_ShutdownIsolate();
@@ skipping 888 matching lines @@
 
 // --- Profiling support ----
 
 // External pprof support for gathering and dumping symbolic
 // information that can be used for better profile reports for
 // dynamically generated code.
 DART_EXPORT void Dart_InitPprofSupport();
 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size);
 
 #endif  // INCLUDE_DART_API_H_