Add support for interrupting an isolate in the vm. Interrupts are

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 217 matching lines @@
 /**
  * An isolate creation and initialization callback function.
  *
  * This callback, provided by the embedder, is called when an isolate needs
  * to be created. The callback should create an isolate and load the
  * required scripts for execution.
  *
  * \param error A structure into which the embedder can place a
  *   C string containing an error message in the case of failures.
  *
- * \return the embedder returns false if the creation and initialization was not
+ * \return The embedder returns false if the creation and initialization was not
  *   successful and true if successful. The embedder is responsible for
  *   maintaining consistency in the case of errors (e.g: isolate is created,
  *   but loading of scripts fails then the embedder should ensure that
  *   Dart_ShutdownIsolate is called on the isolate).
  *   In the case of errors the caller is responsible for freeing the buffer
  *   returned in error containing an error string.
  */
 typedef bool (*Dart_IsolateCreateCallback)(void* callback_data, char** error);
 
 /**
+ * An isolate interrupt callback function.
+ *
+ * This callback, provided by the embedder, is called when an isolate
+ * is interrupted as a result of a call to Dart_InterruptIsolate().
+ * When the callback is called, Dart_CurrentIsolate can be used to
+ * figure out which isolate is being interrupted.
+ *
+ * \return The embedder returns true if the isolate should continue
+ *   execution. If the embedder returns false, the isolate will be
+ *   unwound (currently unimplemented).
+ */
+typedef bool (*Dart_IsolateInterruptCallback)();

[Ivan Posva, 2011/12/14 23:59:50]

Should we also pass the current isolate as a parameter to avoid the obvious call
to Dart_CurrentIsolate?

[turnidge, 2011/12/15 21:30:07]

Discussed offline and decided to keep as-is.

On 2011/12/14 23:59:50, Ivan Posva wrote:

+// TODO(turnidge): Define and implement unwinding.
+
+/**
  * Initializes the VM.
  *
- * \param callback A function to be called during isolate creation.
+ * \param create A function to be called during isolate creation.
  *   See Dart_IsolateCreateCallback.
+ * \param interrupt A function to be called when an isolate is interrupted.
+ *   See Dart_IsolateInterruptCallback.
  *
  * \return True if initialization is successful.
  */
-DART_EXPORT bool Dart_Initialize(Dart_IsolateCreateCallback callback);
+DART_EXPORT bool Dart_Initialize(Dart_IsolateCreateCallback create,
+                                 Dart_IsolateInterruptCallback interrupt);
 
 /**
  * Sets command line flags. Should be called before Dart_Initialize.
  *
  * \param argc The length of the arguments array.
  * \param argv An array of arguments.
  *
  * \return True if VM flags set successfully.
  */
 DART_EXPORT bool Dart_SetVMFlags(int argc, const char** argv);
@@ skipping 111 matching lines @@
  *   until the next call to Dart_ExitScope.
  * \param size Returns the size of the buffer.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_CreateScriptSnapshot(Dart_Handle library,
                                                   uint8_t** buffer,
                                                   intptr_t* size);
 
 
+/**
+ * Schedules an interrupt for the specified isolate.
+ *
+ * Note that the interrupt does not occur immediately. In fact, if
+ * 'isolate' does not execute any further Dart code, then the
+ * interrupt will not occur at all.  If and 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.
+ */
+DART_EXPORT void Dart_InterruptIsolate(Dart_Isolate isolate);
+
 // --- 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
  */
@@ skipping 437 matching lines @@
 /**
  * Retrieves the peer pointer associated with an external String.
  */
 DART_EXPORT Dart_Handle Dart_ExternalStringGetPeer(Dart_Handle object,
                                                    void** peer);
 
 
 /**
  * Returns a String which references an external array of 8-bit codepoints.
  *
- * \param value An array of 8-bit codepoints.  This array must not move.
+ * \param value An array of 8-bit codepoints. This array must not move.
  * \param length The length of the codepoints array.
  * \param peer An external pointer to associate with this string.
  * \param callback A callback to be called when this string is finalized.
  *
  * \return The String object if no error occurs. Otherwise returns
  *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewExternalString8(const uint8_t* codepoints,
                                                 intptr_t length,
                                                 void* peer,
                                                 Dart_PeerFinalizer callback);
 
 /**
  * Returns a String which references an external array of 16-bit codepoints.
  *
- * \param value An array of 16-bit codepoints.  This array must not move.
+ * \param value An array of 16-bit codepoints. This array must not move.
  * \param length The length of the codepoints array.
  * \param peer An external pointer to associate with this string.
  * \param callback A callback to be called when this string is finalized.
  *
  * \return The String object if no error occurs. Otherwise returns
  *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewExternalString16(const uint16_t* codepoints,
                                                  intptr_t length,
                                                  void* peer,
                                                  Dart_PeerFinalizer callback);
 
 /**
  * Returns a String which references an external array of 32-bit codepoints.
  *
- * \param value An array of 32-bit codepoints.  This array must not move.
+ * \param value An array of 32-bit codepoints. This array must not move.
  * \param length The length of the codepoints array.
  * \param peer An external pointer to associate with this string.
  * \param callback A callback to be called when this string is finalized.
  *
  * \return The String object if no error occurs. Otherwise returns
  *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewExternalString32(const uint32_t* codepoints,
                                                  intptr_t length,
                                                  void* peer,
@@ skipping 433 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_