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 1912 matching lines @@
  *
  * \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.
  *
- * \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.
  *
  * 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 368 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 */