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

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 1020 matching lines @@
  * 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_SetMessageNotifyCallback(
     Dart_MessageNotifyCallback message_notify_callback);
 /* TODO(turnidge): Consider moving this to isolate creation so that it
  * 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.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 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.
  *
  * This function may be used by an embedder at a breakpoint to avoid
  * pausing the vm service.
  *
  * This function can indirectly cause the message notify callback to
  * be called.
  *
  * \return true if the vm service requests the program resume
@@ skipping 1745 matching lines @@
     intptr_t* vm_isolate_snapshot_size,
     uint8_t** isolate_snapshot_buffer,
     intptr_t* isolate_snapshot_size,
     uint8_t** instructions_snapshot_buffer,
     intptr_t* instructions_snapshot_size);
 
 
 DART_EXPORT bool Dart_IsRunningPrecompiledCode();
 
 #endif  /* INCLUDE_DART_API_H_ */  /* NOLINT */