OOB messages and general message refactor.

runtime/include/dart_api.h

Index: runtime/include/dart_api.h
===================================================================
--- runtime/include/dart_api.h	(revision 3210)
+++ runtime/include/dart_api.h	(working copy)
@@ -421,81 +421,42 @@
 // --- Messages and Ports ---
 
 /**
- * Messages are used to communicate between isolates.
- */
-typedef struct _Dart_Message* Dart_Message;
-
-/**
  * A port is used to send or receive inter-isolate messages
  */
 typedef int64_t Dart_Port;
 
-const Dart_Port kNoReplyPort = 0;
-
 /**
- * A message posting callback.
+ * A message notification callback.
  *
- * This 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 there is no reply port, then the constant 'kNoReplyPort' is
- * passed as the 'reply_port' parameter.
- *
- * The memory pointed to by 'message' has been allocated by malloc. It
- * is the responsibility of the callback to ensure that free(message)
- * is called once the message has been processed.
- *
- * The callback should return false if it runs into a problem
- * processing this message.
+ * This callback allows the embedder to provide an alternate wakeup
+ * mechanism for the delivery of inter-isolate messages.  It is the
+ * responsibility of the embedder to call Dart_HandleMessage to
+ * process the message.
  */
-typedef bool (*Dart_PostMessageCallback)(Dart_Isolate dest_isolate,
-                                         Dart_Port dest_port_id,
-                                         Dart_Port reply_port_id,
-                                         Dart_Message message);
-// TODO(turnidge): Add a Dart_ReleaseMessage to hide allocation details.
+typedef void (*Dart_MessageNotifyCallback)(Dart_Isolate dest_isolate);
 
-const Dart_Port kCloseAllPorts = 0;
-
 /**
- * A close port callback.
+ * Allows embedders to provide an alternative wakeup mechanism for the
+ * delivery of inter-isolate messages. This setting only applies to
+ * the current isolate.
  *
- * This 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_id);
-
-/**
- * Allows embedders to provide an alternative 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);
+DART_EXPORT void Dart_SetMessageNotifyCallback(
+    Dart_MessageNotifyCallback message_notify_callback);
 // TODO(turnidge): Consider moving this to isolate creation so that it
 // is impossible to mess up.
 
 /**
- * Handles a message on the current isolate.
+ * Handles the next pending message for the current isolate.
  *
  * May generate an unhandled exception error.
  *
- * Note that this function does not free the memory associated with
- * 'dart_message'.
- *
  * \return A valid handle if no error occurs during the operation.
  */
-DART_EXPORT Dart_Handle Dart_HandleMessage(Dart_Port dest_port_id,
-                                           Dart_Port reply_port_id,
-                                           Dart_Message dart_message);
-// TODO(turnidge): Revisit memory management of 'dart_message'.
+DART_EXPORT Dart_Handle Dart_HandleMessage();
 
 /**
  * Processes any incoming messages for the current isolate.
@@ -535,8 +496,6 @@
  * \param port The destination port.
  * \param length The length of the data array.
  * \param data A data array to be sent in the message.
- *
- * \return True if the message was posted.
  */
 DART_EXPORT bool Dart_PostIntArray(Dart_Port port_id,
                                    intptr_t length,
@@ -552,8 +511,6 @@
  *
  * \param port The destination port.
  * \param object An object from the current isolate.
- *
- * \return True if the message was posted.

[Ivan Posva, 2012/01/23 22:00:43]

Why are you removing the documentation for these two functions?

[turnidge, 2012/01/23 22:32:52]

In an earlier rev, I made these void functions.  Then I undid it and forgot to
fix the docs.  Thanks.  Fixed.

  */
 DART_EXPORT bool Dart_Post(Dart_Port port_id, Dart_Handle object);