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
+// 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();
 
+// 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);
 
 
 // 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_