Refactor snapshots pieces to include a section for loading instructions into the heap of a regular …

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 755 matching lines @@
  *
  * \return The embedder must return a handle to a Uint8List containing an
  *   uncompressed tar archive or null.
  */
 typedef Dart_Handle (*Dart_GetVMServiceAssetsArchive)();
 
 /**
  * The current version of the Dart_InitializeFlags. Should be incremented every
  * time Dart_InitializeFlags changes in a binary incompatible way.
  */
-#define DART_INITIALIZE_PARAMS_CURRENT_VERSION (0x00000001)
+#define DART_INITIALIZE_PARAMS_CURRENT_VERSION (0x00000002)
 
 /**
  * Describes how to initialize the VM. Used with Dart_Initialize.
  *
  * \param version Identifies the version of the struct used by the client.
  *   should be initialized to DART_INITIALIZE_PARAMS_CURRENT_VERSION.
  * \param vm_isolate_snapshot A buffer containing a snapshot of the VM isolate
  *   or NULL if no snapshot is provided.
  * \param instructions_snapshot A buffer containing a snapshot of precompiled
  *   instructions, or NULL if no snapshot is provided.
  * \param create A function to be called during isolate creation.
  *   See Dart_IsolateCreateCallback.
  * \param shutdown A function to be called when an isolate is shutdown.
  *   See Dart_IsolateShutdownCallback.
  * \param get_service_assets A function to be called by the service isolate when
  *    it requires the vmservice assets archive.
  *    See Dart_GetVMServiceAssetsArchive.
  */
 typedef struct {
   int32_t version;
-  const uint8_t* vm_isolate_snapshot;
-  const uint8_t* instructions_snapshot;
-  const uint8_t* data_snapshot;
+  const uint8_t* vm_snapshot_data;
+  const uint8_t* vm_snapshot_instructions;
   Dart_IsolateCreateCallback create;
   Dart_IsolateShutdownCallback shutdown;
   Dart_ThreadExitCallback thread_exit;
   Dart_FileOpenCallback file_open;
   Dart_FileReadCallback file_read;
   Dart_FileWriteCallback file_write;
   Dart_FileCloseCallback file_close;
   Dart_EntropySource entropy_source;
   Dart_GetVMServiceAssetsArchive get_service_assets;
 } Dart_InitializeParams;
@@ skipping 47 matching lines @@
  * isolate will be started using that snapshot data. Requires a core snapshot or
  * an app snapshot created by Dart_CreateSnapshot or
  * Dart_CreatePrecompiledSnapshot* from a VM with the same version.
  *
  * Requires there to be no current isolate.
  *
  * \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 snapshot A buffer containing a snapshot of the isolate or
- *   NULL if no snapshot is provided.
+ * \param isolate_snapshot_data
+ * \param isolate_snapshot_instructions Buffers containing a snapshot of the
+ *   isolate or NULL if no snapshot is provided.
  * \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_CreateIsolate(const char* script_uri,
-                                            const char* main,
-                                            const uint8_t* snapshot,
-                                            Dart_IsolateFlags* flags,
-                                            void* callback_data,
-                                            char** error);
+DART_EXPORT Dart_Isolate
+Dart_CreateIsolate(const char* script_uri,
+                   const char* main,
+                   const uint8_t* isolate_snapshot_data,
+                   const uint8_t* isolate_snapshot_instructions,
+                   Dart_IsolateFlags* flags,
+                   void* callback_data,
+                   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
@@ skipping 108 matching lines @@
  * Requires there to be a current isolate.
  *
  * \param buffer Returns a pointer to a buffer containing the
  *   snapshot. This buffer is scope allocated and is only valid
  *   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_CreateSnapshot(uint8_t** vm_isolate_snapshot_buffer,
-                    intptr_t* vm_isolate_snapshot_size,
-                    uint8_t** isolate_snapshot_buffer,
-                    intptr_t* isolate_snapshot_size);
+Dart_CreateSnapshot(uint8_t** vm_snapshot_data_buffer,
+                    intptr_t* vm_snapshot_data_size,
+                    uint8_t** isolate_snapshot_data_buffer,
+                    intptr_t* isolate_snapshot_data_size);
 
 /**
  * Creates a snapshot of the application script loaded in the isolate.
  *
  * A script snapshot can be used for implementing fast startup of applications
  * (skips the script tokenizing and parsing process). A Snapshot of the script
  * can only be created before any dart code has executed.
  *
  * Requires there to be a current isolate which already has loaded script.
  *
  * \param buffer Returns a pointer to a buffer containing
  *   the snapshot. This buffer is scope allocated and is only valid
  *   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(uint8_t** buffer,
-                                                  intptr_t* size);
+DART_EXPORT Dart_Handle
+Dart_CreateScriptSnapshot(uint8_t** script_snapshot_buffer,
+                          intptr_t* script_snapshot_size);
 
 /**
  * Schedules an interrupt for the specified isolate.
  *
  * When the isolate is interrupted, the isolate interrupt callback
  * will be invoked with 'isolate' as the current isolate (see
  * Dart_SetIsolateEventHandler).
  *
  * \param isolate The isolate to be interrupted.
  */
@@ skipping 1787 matching lines @@
  * Loads the root script for current isolate from a script snapshot. The
  * snapshot must have been created by Dart_CreateScriptSnapshot from a VM with
  * the same version.
  *
  * \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);
+DART_EXPORT Dart_Handle
+Dart_LoadScriptFromSnapshot(const uint8_t* script_snapshot_buffer,
+                            intptr_t script_snapshot_size);
 
 /**
  * Loads a dart application via an in-memory kernel program.
  *
  * \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
@@ skipping 357 matching lines @@
 Dart_Precompile(Dart_QualifiedFunctionName entry_points[],
                 uint8_t* jit_feedback,
                 intptr_t jit_feedback_length);
 
 
 /**
  *  Creates a precompiled snapshot.
  *   - A root library must have been loaded.
  *   - Dart_Precompile must have been called.
  *
- *  Outputs an assembly file defining the symbols kVmIsolateSnapshot,
- *  kIsolateSnapshot, kInstructionsSnapshot and kDataSnapshot. The assembly
- *  should be compiled as a static or shared library and linked or loaded by the
- *  embedder.
+ *  Outputs an assembly file defining the symbols
+ *   - kDartVmSnapshotData
+ *   - kDartVmSnapshotInstructions
+ *   - kDartIsolateSnapshotData
+ *   - kDartIsolateSnapshotInstructions
+ *
+ *  The assembly should be compiled as a static or shared library and linked or
+ *  loaded by the embedder.
  *  Running this snapshot requires a VM compiled with DART_PRECOMPILED_SNAPSHOT.
- *  The kVmIsolateSnapshot, kInstructionsSnapshot and kDataSnapshot should be
- *  passed as arguments to Dart_Initialize. The kIsolateSnapshot snapshot should
- *  be passed to Dart_CreateIsolate.
+ *  The kDartVmSnapshotData and kDartVmSnapshotInstructions should be passed to
+ *  Dart_Initialize. The kDartIsolateSnapshotData and
+ *  kDartIsoalteSnapshotInstructions should be passed to Dart_CreateIsolate.
  *
  *  The buffers are scope allocated and are only valid until the next call to
  *  Dart_ExitScope.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle
 Dart_CreateAppAOTSnapshotAsAssembly(uint8_t** assembly_buffer,
                                     intptr_t* assembly_size);
 
 
 /**
  *  Same as Dart_CreateAppAOTSnapshotAsAssembly, except all the pieces are
  *  provided directly as bytes that the embedder can load with mmap. The
- *  instructions piece must be loaded with read and execute permissions; the
+ *  instructions pieces must be loaded with read and execute permissions; the
  *  other pieces may be loaded as read-only.
  */
 DART_EXPORT Dart_Handle
-Dart_CreateAppAOTSnapshotAsBlobs(uint8_t** vm_isolate_snapshot_buffer,
-                                 intptr_t* vm_isolate_snapshot_size,
-                                 uint8_t** isolate_snapshot_buffer,
-                                 intptr_t* isolate_snapshot_size,
-                                 uint8_t** instructions_blob_buffer,
-                                 intptr_t* instructions_blob_size,
-                                 uint8_t** rodata_blob_buffer,
-                                 intptr_t* rodata_blob_size);
+Dart_CreateAppAOTSnapshotAsBlobs(uint8_t** vm_snapshot_data_buffer,
+                                 intptr_t* vm_snapshot_data_size,
+                                 uint8_t** vm_snapshot_instructions_buffer,
+                                 intptr_t* vm_snapshot_instructions_size,
+                                 uint8_t** isolate_snapshot_data_buffer,
+                                 intptr_t* isolate_snapshot_data_size,
+                                 uint8_t** isolate_snapshot_instructions_buffer,
+                                 intptr_t* isolate_snapshot_instructions_size);
 
 
 /**
- *  Creates a snapshot that caches unoptimized code and type feedback for faster
+ *  Creates a snapshot that caches compiled code and type feedback for faster
  *  startup and quicker warmup in a subsequent process.
  *
- *  Outputs a snapshot in four pieces. The vm isolate snapshot,
- *  instructions_blob and rodata_blob should be passed as arguments to
- *  Dart_Initialize. The isolate snapshot should be passed to
- *  Dart_CreateIsolate. The instructions piece must be loaded with execute
- *  permissions; the other pieces may loaded as read-only.
+ *  Outputs a snapshot in two pieces. The pieces should be passed to
+ *  Dart_CreateIsolate in a VM using the same VM snapshot pieces used in the
+ *  current VM. The instructions piece must be loaded with read and execute
+ *  permissions; the data piece may be loaded as read-only.
  *
  *   - Requires the VM to have been started with --load-deferred-eagerly.
  *   - Requires the VM to have not been started with --precompilation.
- *   - Not supported when targeting IA32.
+ *   - Not supported when targeting IA32 or DBC.
  *   - The VM writing the snapshot and the VM reading the snapshot must be the
  *     same version, must be built in the same DEBUG/RELEASE/PRODUCT mode, must
  *     be targeting the same architecture, and must both be in checked mode or
  *     both in unchecked mode.
  *
  *  The buffers are scope allocated and are only valid until the next call to
  *  Dart_ExitScope.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle
-Dart_CreateAppJITSnapshotAsBlobs(uint8_t** isolate_snapshot_buffer,
-                                 intptr_t* isolate_snapshot_size,
-                                 uint8_t** instructions_blob_buffer,
-                                 intptr_t* instructions_blob_size,
-                                 uint8_t** rodata_blob_buffer,
-                                 intptr_t* rodata_blob_size);
+Dart_CreateAppJITSnapshotAsBlobs(uint8_t** isolate_snapshot_data_buffer,
+                                 intptr_t* isolate_snapshot_data_size,
+                                 uint8_t** isolate_snapshot_instructions_buffer,
+                                 intptr_t* isolate_snapshot_instructions_size);
 
 
 /**
  *  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();
 
 
 /**
  *  Print a native stack trace. Used for crash handling.
  */
 DART_EXPORT void Dart_DumpNativeStackTrace(void* context);
 
 #endif /* INCLUDE_DART_API_H_ */ /* NOLINT */