Introduce v8::MicrotasksScope.

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 5432 matching lines @@
 
   /**
    * Types of garbage collections that can be requested via
    * RequestGarbageCollectionForTesting.
    */
   enum GarbageCollectionType {
     kFullGarbageCollection,
     kMinorGarbageCollection
   };
 
+
+  /**
+   * Policy for running microtasks:
+   *   - explicit: microtasks are invoked with RunMicrotasks() method;
+   *   - scoped: microtasks invocation is controlled by MicrotasksScope objects;
+   *   - auto: microtasks are invoked when the script call depth decrements
+   *           to zero.
+   */
+  enum MicrotasksPolicy {

[jochen (gone - plz use gerrit), 2016/03/01 14:26:08]

i'd prefer an enum class

[dgozman, 2016/03/03 01:22:06]

Done.

+    kExplicitMicrotasksInvocation,
+    kScopedMicrotasksInvocation,
+    kAutoMicrotasksInvocation
+  };
+
+
   /**
    * Features reported via the SetUseCounterCallback callback. Do not change
    * assigned numbers of existing items; add new features to the end of this
    * list.
    */
   enum UseCounterFeature {
     kUseAsm = 0,
     kBreakIterator = 1,
     kLegacyConst = 2,
     kMarkDequeOverflow = 3,
@@ skipping 414 matching lines @@
   /**
    * Experimental: Enqueues the callback to the Microtask Work Queue
    */
   void EnqueueMicrotask(Local<Function> microtask);
 
   /**
    * Experimental: Enqueues the callback to the Microtask Work Queue
    */
   void EnqueueMicrotask(MicrotaskCallback microtask, void* data = NULL);
 
-   /**
-   * Experimental: Controls whether the Microtask Work Queue is automatically
-   * run when the script call depth decrements to zero.
+  /**
+   * Experimental: Controls how Microtasks are invoked. See MicrotasksPolicy
+   * for details.
    */
-  void SetAutorunMicrotasks(bool autorun);
+  void SetMicrotasksPolicy(MicrotasksPolicy policy);
+  V8_DEPRECATE_SOON(
+      "Use SetMicrotasksPolicy",
+      void SetAutorunMicrotasks(bool autorun));
 
   /**
-   * Experimental: Returns whether the Microtask Work Queue is automatically
-   * run when the script call depth decrements to zero.
+   * Experimental: Returns the policy controlling how Microtasks are invoked.
    */
-  bool WillAutorunMicrotasks() const;
+  MicrotasksPolicy GetMicrotasksPolicy() const;
+  V8_DEPRECATE_SOON(
+      "Use GetMicrotasksPolicy",
+      bool WillAutorunMicrotasks() const);
 
   /**
    * Experimental: adds a callback to notify the host application after
    * microtasks were run. The callback is triggered by explicit RunMicrotasks
    * call or automatic microtasks execution (see SetAutorunMicrotasks).
    *
    * Callback will trigger even if microtasks were attempted to run,
    * but the microtasks queue was empty and no single microtask was actually
    * executed.
    *
@@ skipping 229 matching lines @@
 };
 
 class V8_EXPORT StartupData {
  public:
   const char* data;
   int raw_size;
 };
 
 
 /**
+ * This scope is used to control microtasks when kScopeMicrotasksInvocation
+ * is used on Isolate. In this mode every non-primitive call to V8 should be
+ * done inside some MicrotasksScope.
+ * Microtasks are executed when topmost MicrotasksScope marked as kRunMicrotasks
+ * exits.
+ * kDoNotRunMicrotasks should be used to annotate calls not intended to trigger
+ * microtasks.
+ */
+class V8_EXPORT MicrotasksScope {
+ public:
+  enum Type { kRunMicrotasks, kDoNotRunMicrotasks };
+
+  MicrotasksScope(Isolate* isolate, Type type);
+  ~MicrotasksScope();
+
+  /**
+   * Runs microtasks if no kRunMicrotasks scope is currently active.
+   */
+  static void PerformCheckpoint(Isolate*);
+
+  /**
+   * Returns current recursion level of scope objects.
+   */
+  static int GetRecursionLevel(Isolate*);
+
+ private:
+  void* internal_;
+
+  // Prevent copying.
+  MicrotasksScope(const MicrotasksScope&);
+  MicrotasksScope& operator=(const MicrotasksScope&);
+};
+
+
+/**
  * EntropySource is used as a callback function when v8 needs a source
  * of entropy.
  */
 typedef bool (*EntropySource)(unsigned char* buffer, size_t length);
 
 
 /**
  * ReturnAddressLocationResolver is used as a callback function when v8 is
  * resolving the location of a return address on the stack. Profilers that
  * change the return address on the stack can use this to resolve the stack
@@ skipping 2435 matching lines @@
  */
 
 
 }  // namespace v8
 
 
 #undef TYPE_CHECK
 
 
 #endif  // INCLUDE_V8_H_