Allow embedders to provide custom message delivery for an isolate.

runtime/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_
 
 #ifdef __cplusplus
 #define DART_EXTERN_C extern "C"
 #else
@@ skipping 61 matching lines @@
 typedef enum {
   kLibraryTag = 0,
   kImportTag,
   kSourceTag,
   kCanonicalizeUrl,
 } Dart_LibraryTag;
 
 typedef void Dart_Snapshot;
 
 typedef int64_t Dart_Port;
+typedef void* Dart_Message;
 
-// Allow the embedder to intercept isolate creation. Both at startup and when
-// spawning new isolates from Dart code.
-// The result returned from this callback is handed to all isolates spawned
-// from the isolate currently being initialized.
-// Return NULL if an error is encountered. The isolate being initialized will
-// be shutdown. No Dart code will execute in before it is shutdown.
+// Allow the embedder to intercept isolate creation. Both at startup
+// and when spawning new isolates from Dart code.  The result returned

[siva, 2011/10/14 21:01:52]

extra space between . and The

[turnidge, 2011/10/14 23:08:02]

Done.

+// from this callback is handed to all isolates spawned from the
+// isolate currently being initialized.
+//
+// Return NULL if an error is encountered. The isolate being
+// initialized will be shutdown. No Dart code will execute before it
+// is shutdown.
+//
 // TODO(iposva): Pass a specification of the app file being spawned.
 typedef void* (*Dart_IsolateInitCallback)(void* data);
 
 typedef void (*Dart_NativeFunction)(Dart_NativeArguments arguments);
 typedef Dart_NativeFunction (*Dart_NativeEntryResolver)(Dart_Handle name,
                                                         int num_of_arguments);
 typedef Dart_Result (*Dart_LibraryTagHandler)(Dart_LibraryTag tag,
                                               Dart_Handle library,
                                               Dart_Handle url);
 
@@ skipping 84 matching lines @@
 
 // Isolate handling.
 DART_EXPORT Dart_Isolate Dart_CreateIsolate(const Dart_Snapshot* snapshot,
                                             void* data);
 DART_EXPORT void Dart_ShutdownIsolate();
 
 DART_EXPORT Dart_Isolate Dart_CurrentIsolate();
 DART_EXPORT void Dart_EnterIsolate(Dart_Isolate isolate);
 DART_EXPORT void Dart_ExitIsolate();
 
 DART_EXPORT Dart_Result Dart_RunLoop();

[siva, 2011/10/14 21:01:52]

I am wondering if we should add a comment to this function stating that this is
a convenience method provided for processing inter-isolate messages and can be
used only if the embedder has not provided any alternate message delivery
mechanism.

[turnidge, 2011/10/14 23:08:02]

Done.

 
+// Messages/ports
+
+// A post message callback allows the embedder to provide an alternate
+// delivery mechanism for inter-isolate messages.  The callback is
+// must eventually cause Dart_HandleMessage to be called to process

[siva, 2011/10/14 21:01:52]

"callback is must eventually" seems incorrect.

[turnidge, 2011/10/14 23:08:02]

Done.

+// the message.
+typedef bool (*Dart_PostMessageCallback)(Dart_Isolate dest_isolate,
+                                         Dart_Port dest_port,
+                                         Dart_Port reply_port,
+                                         Dart_Message message);
+
+// Allow embedders to provide an alternate delivery mechanism for
+// inter-isolate messages.  This setting only applies to the current
+// isolate.
+DART_EXPORT void Dart_SetPostMessageCallback(Dart_PostMessageCallback callback);
+
+// A close port callback allows the embedder to receive notification
+// when a port is closed.  The constant 'kCloseAllPorts' is passed
+// when all active ports are being closed at once.
+typedef void (*Dart_ClosePortCallback)(Dart_Isolate isolate,
+                                       Dart_Port port);
+const Dart_Port kCloseAllPorts = 0;
+
+// Allow embedder to receive notification when a port is closed.  This
+// settign only applies to the current isolate.

[siva, 2011/10/14 21:01:52]

*settign*setting

[turnidge, 2011/10/14 23:08:02]

Done.

+DART_EXPORT void Dart_SetClosePortCallback(Dart_ClosePortCallback callback);
+
+// Directly handle a message on the current isolate.

[siva, 2011/10/14 21:01:52]

"Handle a message.."? not sure what Directly handle implies.

[turnidge, 2011/10/14 23:08:02]

"Directly" meant "immediately", as opposed to queuing it up for later or
something.  I've just dropped the word.

+DART_EXPORT void Dart_HandleMessage(Dart_Port dest_port,
+                                    Dart_Port reply_port,
+                                    Dart_Message dart_message);
+
 
 // Object.
 DART_EXPORT Dart_Result Dart_ObjectToString(Dart_Handle object);
 DART_EXPORT bool Dart_IsNull(Dart_Handle object);
 
 
 // Returns true if the two objects are equal.
 DART_EXPORT Dart_Result Dart_Objects_Equal(Dart_Handle obj1, Dart_Handle obj2);
 
 
@@ skipping 181 matching lines @@
 // 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);
 
 // Check set vm flags.
 DART_EXPORT bool Dart_IsVMFlagSet(const char* flag_name);
 
 #endif  // INCLUDE_DART_API_H_