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.
+ * (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 ---
 
 /**
  * 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 808 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 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..
  *
  * 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_