Move service into VM

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 615 matching lines @@
  * required (for example, if the isolate was created successfully by
  * Dart_CreateIsolate() but the root library fails to load
  * successfully, then the function should call Dart_ShutdownIsolate
  * before returning).
  *
  * When the function returns false, the function should set *error to
  * a malloc-allocated buffer containing a useful error message.  The
  * caller of this function (the vm) will make sure that the buffer is
  * freed.
  *
+ * \param load_script A flag that when false results in no script
+ *   being loaded in the created isolate.

[siva, 2014/01/10 00:01:54]

Comment needs to be removed.

[Cutch, 2014/01/10 21:01:42]

Done.

  * \param script_uri The uri of the script to load.
  *   This uri is non NULL if the isolate is being created using the
  *   spawnUri isolate API. This uri has been canonicalized by the
  *   library tag handler from the parent isolate.
  *   The callback is responsible for loading this script by a call to
  *   Dart_LoadScript or Dart_LoadScriptFromSnapshot.
  *   This uri will be NULL if the isolate is being created using the
  *   spawnFunction isolate API.
  *   The callback is responsible for loading the script used in the
  *   parent isolate by a call to Dart_LoadScript or
  *   Dart_LoadScriptFromSnapshot.
  * \param main The name of the main entry point this isolate will
  *   eventually run.  This is provided for advisory purposes only to
  *   improve debugging messages.  The main function is not invoked by
  *   this function.
  * \param callback_data The callback data which was passed to the
  *   parent isolate when it was created by calling Dart_CreateIsolate().
  * \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 NULL if the creation and
  *   initialization was not successful and the isolate if successful.
  */
 typedef Dart_Isolate (*Dart_IsolateCreateCallback)(const char* script_uri,
                                                    const char* main,
                                                    void* callback_data,
                                                    char** error);
 
+
+/**
+ * The service isolate creation and initialization callback function.
+ *
+ * This callback, provided by the embedder, is called when the vm
+ * needs to create the service isolate. The callback should create an isolate
+ * by calling Dart_CreateIsolate and prepare the isolate to be used as
+ * the service isolate.
+ *
+ * When the function returns NULL, it is the responsibility of this
+ * function to ensure that Dart_ShutdownIsolate has been called if
+ * required.
+ *
+ * When the function returns NULL, the function should set *error to
+ * a malloc-allocated buffer containing a useful error message.  The
+ * caller of this function (the vm) will make sure that the buffer is
+ * freed.
+ *
+ *
+ * \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 NULL if the creation and
+ *   initialization was not successful and the isolate if successful.
+ */
+typedef Dart_Isolate (*Dart_ServiceIsolateCreateCallback)(void* callback_data,
+                                                          char** error);

[siva, 2014/01/10 00:01:54]

I am still debating whether it makes sense to have a new callback for creating
the service isolate or should we add an extra parameter to the regular create
isolate callback indicating a service isolate needs to be created. We can
discuss this with Todd.

+
 /**
  * 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
@@ skipping 88 matching lines @@
  */
 DART_EXPORT bool Dart_Initialize(
     Dart_IsolateCreateCallback create,
     Dart_IsolateInterruptCallback interrupt,
     Dart_IsolateUnhandledExceptionCallback unhandled_exception,
     Dart_IsolateShutdownCallback shutdown,
     Dart_FileOpenCallback file_open,
     Dart_FileReadCallback file_read,
     Dart_FileWriteCallback file_write,
     Dart_FileCloseCallback file_close,
-    Dart_EntropySource entropy_source);
+    Dart_EntropySource entropy_source,
+    Dart_ServiceIsolateCreateCallback service_create);
 
 /**
  * Cleanup state in the VM before process termination.
  *
  * \return True if cleanup is successful.
  */
 DART_EXPORT bool Dart_Cleanup();
 
 /**
  * Sets command line flags. Should be called before Dart_Initialize.
@@ skipping 275 matching lines @@
 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);
 
 
+/**
+ * Returns true if handle is a SendPort.
+ *
+ * \return True if send_port is a SendPort.
+ */
+DART_EXPORT bool Dart_IsSendPort(Dart_Handle send_port);

[siva, 2014/01/10 00:01:54]

Do we need this call if it is only to ensure that Dart_SendPortSend is only
called with valid send ports then I would remove it.

[Cutch, 2014/01/10 21:01:42]

Killed it.

+
+/**
+ * Posts an object to the send port.
+ *
+ * \param send_port A Dart SendPort.
+ * \param object An object from the current isolate.
+ *
+ * \return True if the message was posted.
+ */
+DART_EXPORT bool Dart_SendPortSend(Dart_Handle send_port, Dart_Handle object);

[siva, 2014/01/10 00:01:54]

Dart_SendPortSend seems like an odd name why not call it
Dart_PostMessage(Dart_Handle send_port, Dart_Handle message);

[Cutch, 2014/01/10 21:01:42]

Done.

+
+
 /*
  * ======
  * Scopes
  * ======
  */
 
 /**
  * Enters a new scope.
  *
  * All new local handles will be created in this scope. Additionally,
@@ skipping 1308 matching lines @@
  * 'peer'.
  *
  * \param object An object.
  * \param peer A value to store in the peer field.
  *
  * \return Returns an error if 'object' is a subtype of Null, num, or
  *   bool.
  */
 DART_EXPORT Dart_Handle Dart_SetPeer(Dart_Handle object, void* peer);
 
+
+/*
+ * =======
+ * Service
+ * =======
+ */
+
+/**
+ * Returns the Service isolate initialized and with the dart:vmservice library
+ * loaded and booted.
+ *
+ * This will call the embedder provided Dart_ServiceIsolateCreateCallback to
+ * create the isolate.
+ *
+ * After obtaining the service isolate the embedder specific glue code can
+ * be loaded in and the isolate can be run by the embedder.
+ *
+ * \param callbacK_data A pointer passed to Dart_ServiceIsolateCreateCallback.
+ *
+ * \return Returns NULL if an error occurred.
+ */
+DART_EXPORT Dart_Isolate Dart_GetServiceIsolate(void* callback_data);

[siva, 2014/01/10 00:01:54]

Per offline discussion we should move towards
Dart_GetServicePort();

+
+/**
+ * Register the current isolate with the service. Typically the embedder
+ * will call this function in its Dart_IsolateCreateCallback.
+ *
+ * Requires there to be a current isolate.
+ */
+DART_EXPORT void Dart_RegisterWithService();
+
+/**
+ * Unregister the current isolate from the service. Typically an embedder will
+ * call this function in its Dart_IsolateShutdownCallback.
+ *
+ * Requires there to be a current isolate.
+ */
+DART_EXPORT void Dart_UnregisterFromService();

[siva, 2014/01/10 00:01:54]

Todd and I were discussing this, we were wondering if it makes sense for
isolates to be registered/unregistered by default and we could special case and
allow isolates to just unregister themselves if they did not want to be tracked
(We can even state that the embedder should filter out isolates that it does not
want tracked from the isolates list replies and we will always track all
isolates).
We can discuss this with Todd tomorrow.

[Cutch, 2014/01/10 21:01:42]

I've removed these methods for now and auto-register isolates. In the future if
we need to support unregistering, we can add them back.

+
 #endif  /* INCLUDE_DART_API_H_ */  /* NOLINT */