VM: [Kernel] Split kernel API into 3 steps: ([read binary], parse-binary, bootstrap, load program)

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 RUNTIME_INCLUDE_DART_API_H_
 #define RUNTIME_INCLUDE_DART_API_H_
 
 /** \mainpage Dart Embedding API Reference
@@ skipping 872 matching lines @@
                                             char** error);
 /* TODO(turnidge): Document behavior when there is already a current
  * isolate. */
 
 /**
  * Creates a new isolate from a Dart Kernel file. The new isolate
  * becomes the current isolate.
  *
  * Requires there to be no current isolate.
  *
+ * After this call, the `kernel_program` needs to be supplied to a call to
+ * `Dart_LoadKernel()` which will then take ownership of the memory.
+ *
  * \param script_uri The name of the script this isolate will load.
  *   Provided only for advisory purposes to improve debugging messages.
  * \param main The name of the main entry point this isolate will run.
  *   Provided only for advisory purposes to improve debugging messages.
- * \param kernel A buffer containing the Dart Kernel binary.
- * \param kernel_length The length of the Kernel buffer.
+ * \param kernel_program The `dart::kernel::Program` object.
  * \param flags Pointer to VM specific flags or NULL for default flags.
  * \param callback_data Embedder data.  This data will be passed to
  *   the Dart_IsolateCreateCallback when new isolates are spawned from
  *   this parent isolate.
  * \param error DOCUMENT
  *
  * \return The new isolate is returned. May be NULL if an error
  *   occurs during isolate initialization.
  */
 DART_EXPORT Dart_Isolate Dart_CreateIsolateFromKernel(const char* script_uri,
                                                       const char* main,
-                                                      const uint8_t* kernel,
-                                                      intptr_t kernel_length,
+                                                      void* kernel_program,
                                                       Dart_IsolateFlags* flags,
                                                       void* callback_data,
                                                       char** error);
 /**
  * Shuts down the current isolate. After this call, the current isolate
  * is NULL. Invokes the shutdown callback and any callbacks of remaining
  * weak persistent handles.
  *
  * Requires there to be a current isolate.
  */
@@ skipping 1934 matching lines @@
  * \param buffer A buffer which contains a snapshot of the script.
  * \param buffer_len Length of the passed in buffer.
  *
  * \return If no error occurs, the Library object corresponding to the root
  *   script is returned. Otherwise an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_LoadScriptFromSnapshot(const uint8_t* buffer,
                                                     intptr_t buffer_len);
 
 /**
- * Loads a dart application which was compiled to a Kernel binary.
+ * Loads a dart application via an in-memory kernel program.
  *
- * \param buffer A buffer which contains a Kernel binary.
- * \param buffer_len Length of the passed in buffer.
+ * \param kernel_program The kernel program obtained via
+ *        `Dart_ReadKernelBinary`.
+ *
+ * The VM will take ownership of the `kernel_program` object.
  *
  * \return If no error occurs, the Library object corresponding to the root
  *   script is returned. Otherwise an error handle is returned.
  */
-DART_EXPORT Dart_Handle Dart_LoadKernel(const uint8_t* buffer,
+DART_EXPORT Dart_Handle Dart_LoadKernel(void* kernel_program);
+
+
+/**
+ * Constructs an in-memory kernel program form a binary.
+ *
+ * \param buffer The start of a memory buffer containing the binary format.
+ * \param buffer_len The length of the memory buffer.
+ *
+ * \return kernel_program The `dart::kernel::Program` object.
+ */
+DART_EXPORT void* Dart_ReadKernelBinary(const uint8_t* buffer,
                                         intptr_t buffer_len);
 
 /**
  * Gets the library for the root script for the current isolate.
  *
  * If the root script has not yet been set for the current isolate,
  * this function returns Dart_Null().  This function never returns an
  * error handle.
  *
  * \return Returns the root Library for the current isolate or Dart_Null().
@@ skipping 376 matching lines @@
 
 
 /**
  *  Returns whether the VM only supports running from precompiled snapshots and
  *  not from any other kind of snapshot or from source (that is, the VM was
  *  compiled with DART_PRECOMPILED_RUNTIME).
  */
 DART_EXPORT bool Dart_IsPrecompiledRuntime();
 
 #endif /* INCLUDE_DART_API_H_ */ /* NOLINT */