Add necessary support functions so that embedders can implemented pause on start and exit

runtime/include/dart_api.h

Index: runtime/include/dart_api.h
diff --git a/runtime/include/dart_api.h b/runtime/include/dart_api.h
index 4249382bd9bfa4493d8ebefb3fbc51cdb2694b86..85a8d1fecc597502791711ee50adf5ecb9781f4f 100755
--- a/runtime/include/dart_api.h
+++ b/runtime/include/dart_api.h
@@ -1038,6 +1038,76 @@ DART_EXPORT void Dart_SetMessageNotifyCallback(
  * is impossible to mess up. */
 
 /**
+ * The VM's default message handler supports pausing an isolate before it starts
+ * and before it exits. This is controlled by two VM flags:
+ *
+ *   `--pause-isolates-on-start`
+ *   `--pause-isolates-on-exit`
+ *
+ * When an embedder is using a Dart_MessageNotifyCallback the following
+ * functions can be used to implement pausing on start and exit.
+ */
+
+/**
+ * If the VM flag `--pause-isolates-on-start` was passed this will be true.
+ *
+ * \return A boolean value indicating if pause on start was requested.
+ */
+DART_EXPORT bool Dart_ShouldPauseOnStart();
+
+/**
+ * Override the VM flag `--pause-isolates-on-start` for the current isolate.
+ *
+ * NOTE: This must be called before Dart_IsolateMakeRunnable.
+ */
+DART_EXPORT void Dart_SetShouldPauseOnStart(bool v);

[turnidge, 2016/02/03 21:33:36]

v -> value, here and below.

[Cutch, 2016/02/03 23:04:04]

Done.

+
+/**
+ * Is the current isolate paused on start?
+ *
+ * \return A boolean value indicating if the isolate is paused on start.
+ */
+DART_EXPORT bool Dart_IsPausedOnStart();
+
+/**
+ * Called when the embedder has paused the current isolate on start and when
+ * the embedder has released the isolate.
+ *
+ * \return A boolean value indicating if the isolate is paused on start.
+ */
+DART_EXPORT void Dart_SetPausedOnStart(bool v);
+
+/**
+ * If the VM flag `--pause-isolates-on-exit` was passed this will be true.
+ *
+ * \return A boolean value indicating if pause on start was requested.
+ */
+DART_EXPORT bool Dart_ShouldPauseOnExit();
+
+/**
+ * Override the VM flag `--pause-isolates-on-start` for the current isolate.
+ *
+ * NOTE: This must be called before Dart_IsolateMakeRunnable.
+ */
+DART_EXPORT void Dart_SetShouldPauseOnExit(bool v);
+
+/**
+ * Is the current isolate paused on exit?
+ *
+ * \return A boolean value indicating if the isolate is paused on start.
+ */
+DART_EXPORT bool Dart_IsPausedOnExit();
+
+/**
+ * Called when the embedder has paused the current isolate on start and when
+ * the embedder has released the isolate.
+ *
+ * \return A boolean value indicating if the isolate is paused on start.
+ */
+DART_EXPORT void Dart_SetPausedOnExit(bool v);

[turnidge, 2016/02/03 21:33:36]

We discussed turning this into something like:

void Dart_SetPaused(kPauseExit, true)

I'm torn about whether this is a good idea or not.  I'm just putting it in the
review to document.

[Cutch, 2016/02/03 23:04:04]

Acknowledged.

+
+
+/**
  * Handles the next pending message for the current isolate.
  *
  * May generate an unhandled exception error.
@@ -1047,6 +1117,15 @@ DART_EXPORT void Dart_SetMessageNotifyCallback(
 DART_EXPORT Dart_Handle Dart_HandleMessage();
 
 /**
+ * Handles all pending message for the current isolate.

[turnidge, 2016/02/03 21:33:36]

message -> messages

[Cutch, 2016/02/03 23:04:04]

Done.

+ *
+ * May generate an unhandled exception error.
+ *
+ * \return A valid handle if no error occurs during the operation.
+ */
+DART_EXPORT Dart_Handle Dart_HandleMessages();
+
+/**
  * Handles any pending messages for the vm service for the current
  * isolate.
  *