Add support for native ports in the vm.

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_
 
 /** \mainpage Dart Embedding API Reference
  *
  * Dart is a class-based programming language for creating structured
@@ skipping 504 matching lines @@
  * Requires there to be a current isolate.
  *
  * \param port The destination port.
  * \param object An object from the current isolate.
  *
  * \return True if the message was posted.
  */
 DART_EXPORT bool Dart_Post(Dart_Port port_id, Dart_Handle object);
 
 /**
+ * A native message handling funciton.

[siva, 2012/01/28 00:21:05]

function.

[turnidge, 2012/01/31 20:04:31]

Done.

+ *
+ * This function is associated with a native port by calling
+ * Dart_NewNativePort.

[siva, 2012/01/28 00:21:05]

Should we say:

/**
* A native message handler.
*
* This handler is associated with a ....
...
**/

instead?

[turnidge, 2012/01/31 20:04:31]

Done.

+ */
+typedef void (*Dart_NativeMessageHandler)(Dart_Port dest_port_id,
+                                          Dart_Port reply_port_id,
+                                          uint8_t* data);
+// TODO(turnidge): Make this function take more appropriate arguments.
+
+/**
+ * Creates a new native port.  When messages are received on this
+ * native port, then they will be dispatched to the provided native
+ * message handler.
+ *
+ * \param name The name of this port in debugging messags.

[Søren Gjesse, 2012/01/27 13:33:14]

messags -> messages

[turnidge, 2012/01/31 20:04:31]

Done.

+ * \param handler The C handler to run when messages arrive on the port.
+ * \param allow_concurrent Is it okay to process requests on this
+ *                         native port concurrently?

[siva, 2012/01/28 00:21:05]

Would handle_concurrently be more readable than allow_concurrent?

[turnidge, 2012/01/31 20:04:31]

Changed.

+ *
+ * \return A port id for the native port.
+ */
+DART_EXPORT Dart_Port Dart_NewNativePort(const char* name,
+                                         Dart_NativeMessageHandler func,

[siva, 2012/01/28 00:21:05]

handler instead of func?

[turnidge, 2012/01/31 20:04:31]

Done.

+                                         bool allow_concurrent);
+// TODO(turnidge): Currently allow_concurrent is ignored.
+
+/**
+ * Closes the native port with the given id.
+ *
+ * The port must have been allocated by a call to Dart_NewNativePort.
+ *
+ * \param native_port_id The id of the native port to close.

[siva, 2012/01/28 00:21:05]

s/The id/Id/

[turnidge, 2012/01/31 20:04:31]

What's wrong with "The id"?

[siva, 2012/02/01 00:38:56]

"The id of the native port" sounds weird, I could be wrong.

On 2012/01/31 20:04:31, turnidge wrote:

[turnidge, 2012/02/01 18:51:26]

It sounds okay to my ears.  My guess is that this is a dialectical difference
between American English and Indian English.  There are definitely variations in
how articles are used in the two.

On 2012/02/01 00:38:56, asiva wrote:

+ *
+ * \return Returns true if the port was closed successfully.
+ */
+DART_EXPORT bool Dart_CloseNativePort(Dart_Port native_port_id);
+
+/**
  * Returns a new SendPort with the provided port id.
  */
 DART_EXPORT Dart_Handle Dart_NewSendPort(Dart_Port port_id);
 
 /**
  * Gets the ReceivePort for the provided port id, creating it if necessary.
  *
  * Note that there is at most one ReceivePort for a given port id.
  */
 DART_EXPORT Dart_Handle Dart_GetReceivePort(Dart_Port port_id);
@@ skipping 810 matching lines @@
 
 // --- Profiling support ----
 
 // 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);
 
 #endif  // INCLUDE_DART_API_H_