First step towards generation of application script snapshots

include/dart_api.h

Index: include/dart_api.h
===================================================================
--- include/dart_api.h	(revision 2043)
+++ include/dart_api.h	(working copy)
@@ -344,11 +344,42 @@
 // "pure" dart isolate. Implement and document.
 
 /**
- * Creates a snapshot of the state of the current isolate.
+ * Creates a full snapshot of the current isolate.
+ * (A full snapshot is a compact representation of the dart heap state and
+ *  can be used for fast initialization of an isolate).

[turnidge, 2011/12/05 18:49:00]

So does a "full" snapshot contain the script snapshot?  Cause "full" makes it
sound like it contains everything.  I'm asking because I don't actually know and
I want to figure out if full is the right word here.

[siva, 2011/12/05 21:35:37]

Yes "full" will contain any scripts that were loaded before calling
Dart_CreateSnapshot. It is full snapshot of the current dart heap. The way we
have used it is to load up the core libs and in the case of dartium load up the
corelib and dom libs, then call Dart_CreateSnapshot which ends up creating a
full snapshot of the isolate's heap.

On 2011/12/05 18:49:00, turnidge wrote:

+ * This function can only be called before any dart code has executed.
+ *
+ * \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 handle to the True object if the creation of snapshot was
+ *         successful, otherwise it returns an error handle.
  */

[turnidge, 2011/12/05 18:49:00]

I would use more blank lines in the doc comment to be consistent with the other
doc comments in the file.  Most of them go like this:

/**
  * Brief description starting with a verb.
  * <blank line>
  * Longer description, possibly multiple paragraphs separated by blank lines.
  *
  * \param etc
  */

Maybe drop the parentheses around your description of a full snapshot.

I wouldn't talk about zones, since we don't talk about zones elsewhere in this
header.  Here's what we say in other similar functions:

 "This buffer is scope allocated and is only valid until the next call to
Dart_ExitScope."

Instead of specifying that the True object is returned, you could instead say...

 * \return A valid handle if no error occurs during the operation.

...to be consistent with the other doc comments in this file.

Each paragraph of the doc comment can be formatted in Emacs with M-q.  This
word-wraps that section of the comment and gets rid of the ragged right edge a
bit.

[siva, 2011/12/05 21:35:37]

Done.

-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, this is used for
+ * implementing fast startup of applications (skips the script tokenizing
+ * and parsing process).
+ * This function can only be called before any dart code has executed.
+ *
+ * \param script THe application script for which a snapshot is to be created.

[turnidge, 2011/12/05 18:49:00]

THe -> The.  Or maybe "An"?

[siva, 2011/12/05 21:35:37]

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 handle to the True object if the creation of snapshot was
+ *         successful, otherwise it returns an error handle.
+ */

[turnidge, 2011/12/05 18:49:00]

Similar comments as above.

[siva, 2011/12/05 21:35:37]

Done.

+DART_EXPORT Dart_Handle Dart_CreateScriptSnapshot(Dart_Handle library,
+                                                  uint8_t** buffer,
+                                                  intptr_t* size);
+
+
 // --- Messages and Ports ---
 
 /**
@@ -1176,6 +1207,16 @@
                                         Dart_LibraryTagHandler handler);
 
 /**
+ * Loads the root script for current isolate from a snapshot.
+ *
+ * \param snapshot Buffer which contains a snapshot of the script.

[turnidge, 2011/12/05 18:49:00]

"Buffer" -> "A buffer"

[siva, 2011/12/05 21:35:37]

Done.

+ *
+ * \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* snapshot);
+
+/**
  * Forces all loaded classes and functions to be compiled eagerly in
  * the current isolate..
  *