Add script streaming API

include/v8.h

 // Copyright 2012 the V8 project authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 /** \mainpage V8 API Reference Guide
  *
  * V8 is Google's open source JavaScript engine.
  *
  * This set of documents provides reference material generated from the
  * V8 header file, include/v8.h.
@@ skipping 108 matching lines @@
 class Isolate;
 class DeclaredAccessorDescriptor;
 class ObjectOperationDescriptor;
 class RawOperationDescriptor;
 class CallHandlerHelper;
 class EscapableHandleScope;
 template<typename T> class ReturnValue;
 
 namespace internal {
 class Arguments;
+class BackgroundParsingTask;
+class ExternalStreamingStream;
 class Heap;
 class HeapObject;
 class Isolate;
 class Object;
+class StreamingData;
 template<typename T> class CustomArguments;
 class PropertyCallbackArguments;
 class FunctionCallbackArguments;
 class GlobalHandles;
 }
 
 
 /**
  * General purpose unique identifier.
  */
@@ skipping 938 matching lines @@
     Handle<Integer> resource_line_offset;
     Handle<Integer> resource_column_offset;
     Handle<Boolean> resource_is_shared_cross_origin;
 
     // Cached data from previous compilation (if a kConsume*Cache flag is
     // set), or hold newly generated cache data (kProduce*Cache flags) are
     // set when calling a compile method.
     CachedData* cached_data;
   };
 
+  /**
+   * For streaming incomplete script data to V8. The embedder should implement a
+   * subclass of this class.
+   */
+  class V8_EXPORT ExternalSourceStream {
+   public:
+    enum Encoding { ONE_BYTE, TWO_BYTE, UTF8 };
+
+    ExternalSourceStream(Encoding encoding) : encoding(encoding) {}

[jochen (gone - plz use gerrit), 2014/09/08 11:27:06]

explicit

[marja, 2014/09/08 16:14:46]

(This was removed)

+    virtual ~ExternalSourceStream() {}
+
+    /**
+     * V8 calls this to request the next chunk of data from the embedder. This
+     * function will be called on a background thread, so it's OK to block and
+     * wait for the data, if the embedder doesn't have data yet. Returns the
+     * length of the data returned. The caller takes ownership of the data.
+     *
+     * When streaming UTF-8 data, V8 handles multi-byte characters split between
+     * two data chunks, but doesn't handle multi-byte characters split between
+     * more than two data chunks. The embedder can avoid this problem by always
+     * returning at least 4 bytes of data.
+     */
+    virtual size_t GetMoreData(const uint8_t** src) = 0;

[jochen (gone - plz use gerrit), 2014/09/08 11:27:06]

that's kinda odd, a pure virtual interface shouldn't have a ctor

[marja, 2014/09/08 16:14:47]

Done.

+
+   private:
+    friend class internal::ExternalStreamingStream;
+    const Encoding encoding;

[jochen (gone - plz use gerrit), 2014/09/08 11:27:06]

or friends, or data members

it seems like all this class does is provide a single callback, no?

[marja, 2014/09/08 16:14:47]

Done.

+  };
+
+
+  /**
+   * Source code which can be streamed into V8 in pieces. It will be parsed
+   * while streaming. It can be compiled after the streaming is complete.
+   * StreamedSource must be kept alive while the compilation is ongoing.
+   */
+  class StreamedSource {
+   public:
+    V8_INLINE explicit StreamedSource(ExternalSourceStream* source_stream);
+    ~StreamedSource();
+
+    // Ownership of the CachedData or its buffers is *not* transferred to the
+    // caller. The CachedData object is alive as long as the StreamedSource
+    // object is alive.
+    V8_INLINE const CachedData* GetCachedData() const;
+
+   private:
+    friend class ScriptCompiler;
+    friend class internal::BackgroundParsingTask;

[jochen (gone - plz use gerrit), 2014/09/08 11:27:06]

can we do without friends here?

[marja, 2014/09/08 16:14:47]

Added a private implementation and an accessor to it, so the friends are gone.

+
+    // Prevent copying. Not implemented.
+    StreamedSource(const StreamedSource&);
+    StreamedSource& operator=(const StreamedSource&);
+
+    ExternalSourceStream* source_stream;

[jochen (gone - plz use gerrit), 2014/09/08 11:27:06]

members should end in _

[marja, 2014/09/08 16:14:46]

These are now in an internal struct, so not ending in _.

+
+    // Cached data generated during compilation (if the generate_cached_data
+    // flag is passed to ScriptCompiler::StartStreamingScript). Streamed scripts
+    // cannot utilize already existing cached data.
+    CachedData* cached_data;
+
+    internal::StreamingData* streaming_data;
+  };
+
+  /**
+   * A streaming task which the embedder must run on a background thread to
+   * stream scripts into V8. Returned by ScriptCompiler::StartStreamingScript.
+   */
+  class ScriptStreamingTask {
+   public:
+    virtual ~ScriptStreamingTask() {}
+    virtual void Run() = 0;
+  };
+
   enum CompileOptions {
     kNoCompileOptions = 0,
     kProduceParserCache,
     kConsumeParserCache,
     kProduceCodeCache,
     kConsumeCodeCache,
 
     // Support the previous API for a transition period.
     kProduceDataToCache
   };
@@ skipping 22 matching lines @@
    * \param pre_data Pre-parsing data, as obtained by ScriptData::PreCompile()
    *   using pre_data speeds compilation if it's done multiple times.
    *   Owned by caller, no references are kept when this function returns.
    * \return Compiled script object, bound to the context that was active
    *   when this function was called. When run it will always use this
    *   context.
    */
   static Local<Script> Compile(
       Isolate* isolate, Source* source,
       CompileOptions options = kNoCompileOptions);
+
+  /**
+   * Returns a task which streams script data into V8, or NULL if the script
+   * cannot be streamed. The user is responsible for running the task on a
+   * background thread and deleting it. When ran, the task starts parsing the
+   * script, and it will request data from the StreamedSource as needed. When
+   * ScriptStreamingTask::Run exits, all data has been streamed and the script
+   * can be compiled (see Compile below).
+   *
+   * This API allows to start the streaming with as little data as possible, and
+   * the remaining data (for example, the ScriptOrigin) is passed to Compile.
+   */
+  static ScriptStreamingTask* StartStreamingScript(
+      Isolate* isolate, StreamedSource* source,
+      CompileOptions options = kNoCompileOptions);
+
+  /**
+   * Compiles a streamed script (bound to current context).
+   *
+   * This can only be called after the streaming has finished (the background
+   * task has been run and completed). V8 doesn't construct the source string
+   * during streaming, so the embedder needs to pass the full source here.
+   */
+  static Local<Script> Compile(Isolate* isolate, StreamedSource* source,
+                               Handle<String> full_source_string,
+                               const ScriptOrigin& origin);
 };
 
 
 /**
  * An error message.
  */
 class V8_EXPORT Message {
  public:
   Local<String> Get() const;
   Local<String> GetSourceLine() const;
@@ skipping 5114 matching lines @@
   delete cached_data;
 }
 
 
 const ScriptCompiler::CachedData* ScriptCompiler::Source::GetCachedData()
     const {
   return cached_data;
 }
 
 
+ScriptCompiler::StreamedSource::StreamedSource(ExternalSourceStream* stream)
+    : source_stream(stream), cached_data(NULL), streaming_data(NULL) {}
+
+
+const ScriptCompiler::CachedData*
+ScriptCompiler::StreamedSource::GetCachedData() const {
+  return cached_data;
+}
+
+
 Handle<Boolean> Boolean::New(Isolate* isolate, bool value) {
   return value ? True(isolate) : False(isolate);
 }
 
 
 void Template::Set(Isolate* isolate, const char* name, v8::Handle<Data> value) {
   Set(v8::String::NewFromUtf8(isolate, name), value);
 }
 
 
@@ skipping 547 matching lines @@
  */
 
 
 }  // namespace v8
 
 
 #undef TYPE_CHECK
 
 
 #endif  // V8_H_