Hide Isolate pointer from embedder

runtime/include/dart_api.h

 /*
  * Copyright (c) 2012, 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
@@ skipping 47 matching lines @@
 #else
 #define DART_EXPORT DART_EXTERN_C
 #endif
 #else
 #error Tool chain not supported.
 #endif
 #endif
 
 #include <assert.h>
 
+
+/*
+ * ========
+ * Isolates
+ * ========
+ */
+
+/**
+ * A port is used to send or receive inter-isolate messages. It is also used
+ * to identify an isolate (see Dart_Isolate).
+ */
+typedef int64_t Dart_Port;
+
+
+/**
+ * An isolate is the unit of concurrency in Dart. Each isolate has
+ * its own memory and thread of control. No state is shared between
+ * isolates. Instead, isolates communicate by message passing.
+ *
+ * Each thread keeps track of its current isolate, which is the
+ * isolate which is ready to execute on the current thread. The
+ * current isolate may be DART_ILLEGAL_ISOLATE, in which case no isolate is
+ * ready to execute. Most of the Dart apis require there to be a current
+ * isolate in order to function without error. The current isolate is
+ * set by any call to Dart_CreateIsolate or Dart_EnterIsolate.
+ */
+typedef Dart_Port Dart_Isolate;
+
+/**
+ * DART_ILLEGAL_ISOLATE is an isolate id that is  guaranteed never to be associated
+ * with a valid isolate.
+ */
+#define DART_ILLEGAL_ISOLATE ((Dart_Isolate) 0)
+
 /*
  * =======
  * Handles
  * =======
  */
 
 /**
- * An isolate is the unit of concurrency in Dart. Each isolate has
- * its own memory and thread of control. No state is shared between
- * isolates. Instead, isolates communicate by message passing.
- *
- * Each thread keeps track of its current isolate, which is the
- * isolate which is ready to execute on the current thread. The
- * current isolate may be NULL, in which case no isolate is ready to
- * execute. Most of the Dart apis require there to be a current
- * isolate in order to function without error. The current isolate is
- * set by any call to Dart_CreateIsolate or Dart_EnterIsolate.
- */
-typedef struct _Dart_Isolate* Dart_Isolate;
-
-/**
  * An object reference managed by the Dart VM garbage collector.
  *
  * Because the garbage collector may move objects, it is unsafe to
  * refer to objects directly. Instead, we refer to objects through
  * handles, which are known to the garbage collector and updated
  * automatically when the object is moved. Handles should be passed
  * by value (except in cases like out-parameters) and should never be
  * allocated on the heap.
  *
  * Most functions in the Dart Embedding API return a handle. When a
@@ skipping 831 matching lines @@
  * Returns the callback data associated with the current Isolate. This data was
  * passed to the isolate when it was created.
  */
 DART_EXPORT void* Dart_CurrentIsolateData();
 
 /**
  * Returns the callback data associated with the specified Isolate. This data
  * was passed to the isolate when it was created.
  * The embedder is responsible for ensuring the consistency of this data
  * with respect to the lifecycle of an Isolate.
+ *
+ * \return pointer to data or NULL if the isolate could not be found.
  */
 DART_EXPORT void* Dart_IsolateData(Dart_Isolate isolate);
 
 /**
  * Returns the debugging name for the current isolate.
  *
  * This name is unique to each isolate and should only be used to make
  * debugging messages more comprehensible.
  */
 DART_EXPORT Dart_Handle Dart_DebugName();
 
 /**
  * Enters an isolate. After calling this function,
  * the current isolate will be set to the provided isolate.
  *
  * Requires there to be no current isolate. Multiple threads may not be in
  * the same isolate at once.
+ *
+ * \return true if isolate was entered, false otherwise.
  */
-DART_EXPORT void Dart_EnterIsolate(Dart_Isolate isolate);
+DART_EXPORT bool Dart_EnterIsolate(Dart_Isolate isolate);
 
 /**
  * Notifies the VM that the current isolate is about to make a blocking call.
  */
 DART_EXPORT void Dart_IsolateBlocked();
 
 /**
  * Notifies the VM that the current isolate is no longer blocked.
  */
 DART_EXPORT void Dart_IsolateUnblocked();
@@ skipping 64 matching lines @@
                                                   intptr_t* size);
 
 /**
  * Schedules an interrupt for the specified isolate.
  *
  * When the isolate is interrupted, the isolate interrupt callback
  * will be invoked with 'isolate' as the current isolate (see
  * Dart_IsolateInterruptCallback).
  *
  * \param isolate The isolate to be interrupted.
+ *
+ * \return true if isolate is scheduled to be be interrupted, false otherwise.
  */
-DART_EXPORT void Dart_InterruptIsolate(Dart_Isolate isolate);
+DART_EXPORT bool Dart_InterruptIsolate(Dart_Isolate isolate);
 
 /**
  * Make isolate runnable.
  *
  * When isolates are spawned this function is used to indicate that
  * the creation and initialization (including script loading) of the
  * isolate is complete and the isolate can start.
  * This function does not expect there to be a current isolate.
  *
  * \param isolate The isolate to be made runnable.
+ *
+ * \return true if isolate was made runnable, false otherwise.
  */
 DART_EXPORT bool Dart_IsolateMakeRunnable(Dart_Isolate isolate);
 
 
 /*
  * ==================
  * Messages and Ports
  * ==================
  */
 
 /**
- * A port is used to send or receive inter-isolate messages
+ * DART_ILLEGAL_PORT is a port number guaranteed never to be associated with a
+ * valid port.
  */
-typedef int64_t Dart_Port;
-
-/**
- * ILLEGAL_PORT is a port number guaranteed never to be associated with a valid
- * port.
- */
-#define ILLEGAL_PORT ((Dart_Port) 0)
+#define DART_ILLEGAL_PORT ((Dart_Port) 0)
 
 /**
  * A message notification callback.
  *
  * 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 void (*Dart_MessageNotifyCallback)(Dart_Isolate dest_isolate);
@@ skipping 1694 matching lines @@
  * \param isolate An isolate
  *
  * \return Returns true if 'isolate' is the service isolate.
  */
 DART_EXPORT bool Dart_IsServiceIsolate(Dart_Isolate isolate);
 
 
 /**
  * Returns the port that script load requests should be sent on.
  *
- * \return Returns the port for load requests or ILLEGAL_PORT if the service
- * isolate failed to startup or does not support load requests.
+ * \return Returns the port for load requests or DART_ILLEGAL_PORT if the
+ * service isolate failed to startup or does not support load requests.
  */
 DART_EXPORT Dart_Port Dart_ServiceWaitForLoadPort();
 
 
 /**
  * A service request callback function.
  *
  * These callbacks, registered by the embedder, are called when the VM receives
  * a service request it can't handle and the service request command name
  * matches one of the embedder registered handlers.
@@ skipping 43 matching lines @@
  * NOTE: If multiple callbacks with the same name are registered, only the
  * last callback registered will be remembered.
  */
 DART_EXPORT void Dart_RegisterRootServiceRequestCallback(
     const char* name,
     Dart_ServiceRequestCallback callback,
     void* user_data);
 
 
 #endif  /* INCLUDE_DART_API_H_ */  /* NOLINT */