Allow embedders to provide custom message delivery for an isolate.

runtime/include/dart_api.h

Index: runtime/include/dart_api.h
===================================================================
--- runtime/include/dart_api.h	(revision 448)
+++ runtime/include/dart_api.h	(working copy)
@@ -79,13 +79,17 @@
 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);
 
@@ -192,7 +196,39 @@
 
 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);