Adding a SetRAILMode 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 5339 matching lines @@
 
     // Only valid for CODE_ADD_LINE_POS_INFO
     struct line_info_t line_info;
 
     // New location of instructions. Only valid for CODE_MOVED.
     void* new_code_start;
   };
 };
 
 /**
+ * Option flags passed to the SetRAILMode function.
+ * See documentation https://developers.google.com/web/tools/chrome-devtools/
+ * profile/evaluate-performance/rail
+ */
+enum RAILMode {
+  // Default performance mode: V8 will optimize for both latency and
+  // throughput in this mode.
+  PERFORMANCE_DEFAULT,
+  // Response performance mode: In this mode very low virtual machine latency
+  // is provided. V8 will try to avoid JavaScript execution interruptions.
+  // Throughput may be throttled.
+  PERFORMANCE_RESPONSE,

[alph, 2016/05/24 21:16:58]

The mode names look misleading. They should not be browser driven. How about
make them somewhat embedder agnostic, e.g. OPTIMIZE_LATENCY, OPTIMIZE_THROUGHPUT
etc.

+  // Animation performance mode: In this mode low virtual machine latency is
+  // provided. V8 will try to avoid as many JavaScript execution interruptions
+  // as possible. Throughput may be throttled
+  PERFORMANCE_ANIMATION,

[alph, 2016/05/24 21:16:58]

It's not clear what's the difference from RESPONSE.

+  // Idle performance mode: The embedder is idle. V8 can complete deferred work
+  // in this mode.
+  PERFORMANCE_IDLE,
+  // Load performance mode: In this mode high throughput is provided. V8 may
+  // turn off latency optimizations.
+  PERFORMANCE_LOAD

[pfeldman, 2016/05/24 23:36:01]

+1 to what alph@ is saying. not only v8 should operate v8 terms as opposed to
the embedder terms, but RAIL by itself is more of a product terminology rather
than a technical one. There is no consensus on the load phase characteristics,
it can be substituted by another model, etc.

+};
+
+/**
  * Option flags passed to the SetJitCodeEventHandler function.
  */
 enum JitCodeEventOptions {
   kJitCodeEventDefault = 0,
   // Generate callbacks for already existent code.
   kJitCodeEventEnumExisting = 1
 };
 
 
 /**
@@ skipping 781 matching lines @@
    */
   void IsolateInForegroundNotification();
 
   /**
    * Optional notification that the isolate switched to the background.
    * V8 uses these notifications to guide heuristics.
    */
   void IsolateInBackgroundNotification();
 
   /**
+   * Optional notification to tell V8 the current performance requirements
+   * of the embedder based on RAIL.
+   * V8 uses these notifications to guide heuristics.
+   * This is an unfinished experimental feature. Semantics and implementation
+   * may change frequently.
+   */
+  void SetRAILMode(RAILMode rail_mode);
+
+  /**
    * Allows the host application to provide the address of a function that is
    * notified each time code is added, moved or removed.
    *
    * \param options options for the JIT code event handler.
    * \param event_handler the JIT code event handler, which will be invoked
    *     each time code is added, moved or removed.
    * \note \p event_handler won't get notified of existent code.
    * \note since code removal notifications are not currently issued, the
    *     \p event_handler may get notifications of code that overlaps earlier
    *     code notifications. This happens when code areas are reused, and the
@@ skipping 2573 matching lines @@
  */
 
 
 }  // namespace v8
 
 
 #undef TYPE_CHECK
 
 
 #endif  // INCLUDE_V8_H_