First step towards generation of application script snapshots

include/dart_api.h

 // Copyright (c) 2011, 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
  *
  * Dart is a class-based programming language for creating structured
@@ skipping 326 matching lines @@
  * Exits an isolate. After this call, Dart_CurrentIsolate will
  * return NULL.
  *
  * Requires there to be a current isolate.
  */
 DART_EXPORT void Dart_ExitIsolate();
 // TODO(turnidge): We don't want users of the api to be able to exit a
 // "pure" dart isolate. Implement and document.
 
 /**
- * Creates a snapshot of the state of the current isolate.
+ * Creates a full snapshot of the current isolate heap.
+ *
+ * A full snapshot is a compact representation of the dart heap state and
+ * can be used for fast initialization of an isolate. Snapshot of the heap
+ * can only be done before any dart code has executed.

[turnidge, 2011/12/05 23:23:36]

Instead  of "Snapshot ...  can only be done ...", how about "A snapshot ... can
only be created .."

[siva, 2011/12/06 00:23:34]

Done.

+ *
+ * Requires there to be a current isolate.
+ *
+ * \param buffer Returns a pointer to a buffer containing the
+ *   snapshot.  The buffer is allocated in the current Api zone and
+ *   will be delete when the current Api scope is exited using
+ *   Dart_ExitScope.

[turnidge, 2011/12/05 23:23:36]

One of my earlier comments got skipped:

[siva, 2011/12/06 00:23:34]

Done, Somehow missed it the first time around.

On 2011/12/05 23:23:36, turnidge wrote:

+ * \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** snaphot_buffer,
-                                            intptr_t* snapshot_size);
+DART_EXPORT Dart_Handle Dart_CreateSnapshot(uint8_t** buffer,
+                                            intptr_t* size);
+
+/**
+ * Creates a snapshot of the specified application script.
+ *
+ * A script snapshot can be used for implementing fast startup of applications
+ * (skips the script tokenizing and parsing process). Snapshot of a script
+ * can only be done before any dart code has executed.

[turnidge, 2011/12/05 23:23:36]

Snapshot -> A snapshot
done -> created

[siva, 2011/12/06 00:23:34]

Done.

+ *
+ * Requires there to be a current isolate.
+ *
+ * \param script An application script for which a snapshot is to be
+ *  created.

[turnidge, 2011/12/05 23:23:36]

Need extra space to line up "created".  Missing * on next line.

[siva, 2011/12/06 00:23:34]

Done.

+   \param buffer Returns a pointer to a buffer containing
+ *   the snapshot.  The buffer is allocated in the current Api zone and
+ *   will be deleted when the current Api scope is exited using
+ *   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(Dart_Handle library,
+                                                  uint8_t** buffer,
+                                                  intptr_t* size);
+
 
 // --- Messages and Ports ---
 
 /**
  * Messages are used to communicate between isolates.
  */
 typedef struct _Dart_Message* Dart_Message;
 
 /**
  * A port is used to send or receive inter-isolate messages
@@ skipping 856 matching lines @@
 /**
  * Loads the root script for the current isolate.
  *
  * TODO(turnidge): Document.
  */
 DART_EXPORT Dart_Handle Dart_LoadScript(Dart_Handle url,
                                         Dart_Handle source,
                                         Dart_LibraryTagHandler handler);
 
 /**
+ * Loads the root script for current isolate from a snapshot.
+ *
+ * \param buffer A buffer which contains a snapshot of the script.
+ *
+ * \return if no error occurs, the Library object corresponding to the root

[turnidge, 2011/12/05 23:23:36]

Capitalize "if"

[siva, 2011/12/06 00:23:34]

Done.

+ *   script is returned. Otherwise an error handle is returned.
+ **/
+DART_EXPORT Dart_Handle Dart_LoadScriptFromSnapshot(const uint8_t* buffer);
+
+/**
  * Forces all loaded classes and functions to be compiled eagerly in
  * the current isolate..
  *
  * TODO(turnidge): Document.
  */
 DART_EXPORT Dart_Handle Dart_CompileAll();
 
 /**
  * Is this object a Library?
  */
@@ skipping 38 matching lines @@
 
 // --- Profiling support ----
 
 // External pprof support for gathering and dumping symbolic
 // information that can be used for better profile reports for
 // dynamically generated code.
 DART_EXPORT void Dart_InitPprofSupport();
 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size);
 
 #endif  // INCLUDE_DART_API_H_