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 510)
+++ 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
+// 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);
 
@@ -190,9 +194,60 @@
 DART_EXPORT void Dart_EnterIsolate(Dart_Isolate isolate);
 DART_EXPORT void Dart_ExitIsolate();
 
+// A convenience routine which processes any incoming messages for the
+// current isolate. The routine exits when all ports to the current
+// isolate are closed.
+//
+// This routine may only be used when the embedder has not provided an
+// alternate message delivery mechanism with Dart_SetPostMessageCallback.
 DART_EXPORT Dart_Result Dart_RunLoop();
 
+// Messages/ports

[Anton Muhin, 2011/10/18 17:19:58]

nit: missing trailing dot I believe.

[turnidge, 2011/10/18 17:33:40]

This comment is intended as a title for the section.  It isn't a sentence so it
feels wrong to end it with a period.

 
+// A post message callback allows the embedder to provide an alternate

[Anton Muhin, 2011/10/18 17:19:58]

nit: alternate -> alternative ?

[turnidge, 2011/10/18 17:33:40]

Done.

+// delivery mechanism for inter-isolate messages. It is the
+// responsibility of the embedder to call Dart_HandleMessage to
+// process the message.
+//
+// If there is no reply port, then the constant 'kNoReplyPort' is
+// passed as the reply_port parameter.

[Anton Muhin, 2011/10/18 17:19:58]

nit: reply_port -> 'reply_port' ?

[turnidge, 2011/10/18 17:33:40]

Done.

+//
+// The memory pointed to by 'message' has been allocated by malloc.  It
+// is the responsibility of the callback to ensure that free(message)

[Anton Muhin, 2011/10/18 17:19:58]

hmm, you're saying "Claims ownership of the memory pointed to by 'message' and
will ensure that free(message) is called." in PortMap::PostMessage.

Contradiction?

[turnidge, 2011/10/18 17:33:40]

Nope.  PortMap::PostMessage claims ownership from it's caller and hands off
ownership to the callback.

+// is called once the message has been processed.
+//
+// TODO(turnidge): Add a Dart_ReleaseMessage to hide allocation details?
+typedef bool (*Dart_PostMessageCallback)(Dart_Isolate dest_isolate,

[Anton Muhin, 2011/10/18 17:19:58]

what's the semantics of returned value?

[turnidge, 2011/10/18 17:33:40]

Added:

// The callback should return true if the message was successfully
// posted.

[Anton Muhin, 2011/10/18 17:40:54]

Great.  Minor correction: not posted, but something like queued or processed.

On 2011/10/18 17:33:40, turnidge wrote:

+                                         Dart_Port dest_port,
+                                         Dart_Port reply_port,
+                                         Dart_Message message);
+const Dart_Port kNoReplyPort = 0;
+
+// A close port callback allows the embedder to receive notification
+// when a port is closed. The constant 'kCloseAllPorts' is passed as
+// the 'port' parameter when all active ports are being closed at
+// once.
+typedef void (*Dart_ClosePortCallback)(Dart_Isolate isolate,
+                                       Dart_Port port);
+const Dart_Port kCloseAllPorts = 0;
+
+// Allows embedders to provide an alternate mechanism for sending
+// inter-isolate messages. This setting only applies to the current
+// isolate.
+//
+// Most embedders will only call this function once, before isolate
+// execution begins.  If this function is called after isolate
+// execution begins, the embedder is responsible for threading issues.
+DART_EXPORT void Dart_SetMessageCallbacks(
+    Dart_PostMessageCallback post_message_callback,
+    Dart_ClosePortCallback close_port_callback);
+
+// Handle a message on the current isolate.
+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);