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

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 a085a724bf47fe05981d292b3f56300031dd09c4..ade83c46fbe1aa527bade2d7a59d72ef531fed6a 100644
--- a/runtime/include/dart_api.h
+++ b/runtime/include/dart_api.h
@@ -890,12 +890,14 @@ DART_EXPORT Dart_Isolate Dart_CreateIsolate(const char* script_uri,
  *
  * 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
@@ -907,8 +909,7 @@ DART_EXPORT Dart_Isolate Dart_CreateIsolate(const char* script_uri,
  */
 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);
@@ -2841,14 +2842,26 @@ DART_EXPORT Dart_Handle Dart_LoadScriptFromSnapshot(const uint8_t* buffer,
 /**
  * Loads a dart application which was compiled to a Kernel binary.
  *
- * \param buffer A buffer which contains a Kernel binary.
- * \param buffer_len Length of the passed in buffer.
+ * \param kernel_program The `dart::kernel::Program` object returned by .

[Kevin Millikin (Google), 2016/11/22 15:51:17]

Missing the name of the function that returns the program.

[kustermann, 2016/11/23 08:31:46]

Done.

+ *
+ * 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,
-                                        intptr_t buffer_len);
+DART_EXPORT Dart_Handle Dart_LoadKernel(void* kernel_program);
+
+
+/**
+ * Lonstructs a kernel program form a binary.

[Kevin Millikin (Google), 2016/11/22 15:51:17]

Lonstructs == Load + constructs?

[kustermann, 2016/11/23 08:31:46]

Precisely!

Done

+ *
+ * \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_ParseKernelBinary(const uint8_t* buffer,

[Kevin Millikin (Google), 2016/11/22 15:51:17]

I don't think of this as parsing.  Deserializing, but maybe that's too long. 
"ReadKernelBinary"?  "LoadKernelBinary"?

[kustermann, 2016/11/23 08:31:46]

Then I'll go with ReadKernelBinary ("load" is already used for loading libraries
from the kernel program into the isolate)

+                                         intptr_t buffer_len);
 
 /**
  * Gets the library for the root script for the current isolate.