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 460)
+++ 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,51 @@
 DART_EXPORT void Dart_EnterIsolate(Dart_Isolate isolate);
 DART_EXPORT void Dart_ExitIsolate();
 
+// A convenience routine for which processes any incoming messages for

[siva, 2011/10/14 23:50:32]

routine which

[turnidge, 2011/10/17 18:38:48]

Done.

[Anton Muhin, 2011/10/18 07:01:03]

I think Siva meant "A convenience routine which processes...", w/o for

On 2011/10/17 18:38:48, turnidge wrote:

[turnidge, 2011/10/18 16:42:14]

Yeah, forgot to upload, sorry.

On 2011/10/18 07:01:03, antonmuhin wrote:

+// the current isolate. The routine exits when all ports to the
+// current isolate are closed

[siva, 2011/10/14 23:50:32]

closed.

[turnidge, 2011/10/17 18:38:48]

Done.

[Anton Muhin, 2011/10/18 07:01:03]

Nit, missing trailing dot.

On 2011/10/17 18:38:48, turnidge wrote:

[turnidge, 2011/10/18 16:42:14]

Ditto upload.

On 2011/10/18 07:01:03, antonmuhin wrote:

+//
+// 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
 
+// A post message callback allows the embedder to provide an alternate
+// delivery mechanism for inter-isolate messages. The callback must

[Anton Muhin, 2011/10/17 15:20:29]

is it indeed a must?  May I just drop some messages?

[turnidge, 2011/10/17 18:38:48]

I suppose it isn't a must, if you don't care about getting the messages.  I have
rephrased it...

// A post message callback allows the embedder to provide an alternate
// delivery mechanism for inter-isolate messages. It is the
// responsibility of the embedder to call Dart_HandleMessage to
// process the message.

If this is still too prescriptive, let me know.

[Anton Muhin, 2011/10/18 07:01:03]

I like your new wording, thanks a lot.

On 2011/10/17 18:38:48, turnidge wrote:

+// eventually cause Dart_HandleMessage to be called to process the
+// message.
+//
+// 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 07:01:03]

that somewhat leaks the abstraction---we have this alias for Dart_Message.  You
may want to add Dart_ReleaseMessage(Dart_Message), but feel free to ignore if it
smells like overengineering.

[turnidge, 2011/10/18 16:42:14]

I agree that this leaks the abstraction.  I've added a TODO to address it later.
 We will need to add additional message processing functions for those who will
need to send the message over the wire.  I will address it then.

+// is called once the message has been processed.
+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

[Anton Muhin, 2011/10/17 15:20:29]

nit: it looks like 3rd person is preferred: allow[s], etc.

[turnidge, 2011/10/17 18:38:48]

Done.

+// inter-isolate messages. This setting only applies to the current
+// isolate.
+DART_EXPORT void Dart_SetPostMessageCallback(Dart_PostMessageCallback callback);

[Anton Muhin, 2011/10/17 15:20:29]

is _SetPostMessageCallback thread safe?  Imagine message being  sent while I am
changing the callback.  That's probably should as I have no way to control this,
but that probably should be explicit.

[turnidge, 2011/10/17 18:38:48]

Added some documentation around this.

I also combined SetPostMessageCallback and SetClosePortCallback to show the user
that they should be overridden together.

+
+// A close port callback allows the embedder to receive notification
+// when a port is closed. The constant 'kCloseAllPorts' is passed

[Anton Muhin, 2011/10/17 15:20:29]

nit: in port parameter?

[turnidge, 2011/10/17 18:38:48]

Done.

+// 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
+// setting only applies to the current isolate.
+DART_EXPORT void Dart_SetClosePortCallback(Dart_ClosePortCallback callback);
+
+// Handle a message on the current isolate.
+DART_EXPORT void Dart_HandleMessage(Dart_Port dest_port,

[Anton Muhin, 2011/10/17 15:20:29]

do we need to pass ports around?  maybe we can bundle them into a message (at
least at API level)?

[turnidge, 2011/10/17 18:38:48]

They are sort of useless for the default, standalone embedding.  But once we
start needing to communicate with isolates in other processes and on other
machines, then the embedder will need access to the port number (which is more
of a local entity) so that they can map to the correct non-local isolate/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);