Per-isolate v8::Locker and v8::Unlocker

include/v8.h

Index: include/v8.h
diff --git a/include/v8.h b/include/v8.h
index d15d024dc3ce11164f9b28eb026f8fa2c74e93d7..c2a95c2f6836cecc168bb0a8aed7255b59a432c0 100644
--- a/include/v8.h
+++ b/include/v8.h
@@ -3321,14 +3321,14 @@ class V8EXPORT Context {
  * to the user of V8 to ensure (perhaps with locking) that this
  * constraint is not violated.
  *
- * More then one thread and multiple V8 isolates can be used
- * without any locking if each isolate is created and accessed
- * by a single thread only. For example, one thread can use
- * multiple isolates or multiple threads can each create and run
- * their own isolate.
+ * If the isolate is only accessed on a single thread, it can be

[Vitaly Repeshko, 2011/04/21 21:15:27]

I think this paragraph adds little value and should be removed.

+ * entered and exited on that thread at any time (subject to proper
+ * nesting of Enter and Exit operations). More than one isolate may
+ * be entered on any single thread.
  *
- * If you wish to start using V8 isolate in more then one thread
- * you can do this by constructing a v8::Locker object to guard
+ * If the isolate is accessed from multiple threads of a process,

[Vitaly Repeshko, 2011/04/21 21:15:27]

"the isolate" -> "an isolate"
"of a process" -> ", even when accesses are synchronized by external means"

+ * its use MUST be protected with appropriate v8::Locker use.

[Vitaly Repeshko, 2011/04/21 21:15:27]

Replace the line with "v8::Locker must be used."

+ * You can do this by constructing a v8::Locker object to guard

[Vitaly Repeshko, 2011/04/21 21:15:27]

Replace the paragraph with "v8::Locker is a scoped lock object. While it's
active (i.e. between its construction and destruction) the current thread is
allowed to use the locked isolate. V8 guarantees that an isolate can be locked
by at most one thread at any time. In other words, the scope of a v8::Locker is
a critical section.

Sample usage:"

  * access to the isolate. After the code using V8 has completed
  * for the current thread you can call the destructor.  This can
  * be combined with C++ scope-based construction as follows
@@ -3338,7 +3338,7 @@ class V8EXPORT Context {
  * \code
  * ...
  * {
- *   v8::Locker locker;
+ *   v8::Locker locker(isolate);

[Vitaly Repeshko, 2011/04/21 21:15:27]

This snippet should show using Isolate::Scope.

  *   ...
  *   // Code using V8 goes here.
  *   ...
@@ -3351,7 +3351,7 @@ class V8EXPORT Context {
  *
  * \code
  * {

[Vitaly Repeshko, 2011/04/21 21:15:27]

There should be isolate->Exit() before '{' and isolate->Enter() after '}'.

- *   v8::Unlocker unlocker;
+ *   v8::Unlocker unlocker(isolate);
  *   ...
  *   // Code not using V8 goes here while V8 can run in another thread.
  *   ...
@@ -3393,14 +3393,22 @@ class V8EXPORT Context {
  */

[Vitaly Repeshko, 2011/04/21 21:15:27]

We need a special section describing the legacy usage with no explicit
entering/exiting of the default isolate.

 class V8EXPORT Unlocker {
  public:
-  Unlocker();
+  /**
+   * Initialize Unlocker for a given Isolate. NULL means default isolate.
+   */
+  explicit Unlocker(Isolate* isolate = NULL);
   ~Unlocker();
+ private:
+  internal::Isolate* isolate_;
 };
 
 
 class V8EXPORT Locker {
  public:
-  Locker();
+  /**
+   * Initialize Locker for a given Isolate. NULL means default isolate.
+   */
+  explicit Locker(Isolate* isolate = NULL);
   ~Locker();
 
   /**
@@ -3418,9 +3426,10 @@ class V8EXPORT Locker {
   static void StopPreemption();
 
   /**
-   * Returns whether or not the locker is locked by the current thread.
+   * Returns whether or not the locker for a given isolate, or default isolate if NULL is given,

[Vitaly Repeshko, 2011/04/21 21:15:27]

nit: Line too long.

+   * is locked by the current thread.
    */
-  static bool IsLocked();
+  static bool IsLocked(Isolate* isolate = NULL);
 
   /**
    * Returns whether v8::Locker is being used by this V8 instance.
@@ -3430,6 +3439,7 @@ class V8EXPORT Locker {
  private:
   bool has_lock_;
   bool top_level_;
+  internal::Isolate* isolate_;
 
   static bool active_;