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

include/v8.h

 // Copyright 2007-2009 the V8 project authors. All rights reserved.
 // Redistribution and use in source and binary forms, with or without
 // modification, are permitted provided that the following conditions are
 // met:
 //
 //     * Redistributions of source code must retain the above copyright
 //       notice, this list of conditions and the following disclaimer.
 //     * Redistributions in binary form must reproduce the above
 //       copyright notice, this list of conditions and the following
 //       disclaimer in the documentation and/or other materials provided
@@ skipping 3303 matching lines @@
 
 /**
  * Multiple threads in V8 are allowed, but only one thread at a time
  * is allowed to use any given V8 isolate. See Isolate class
  * comments. The definition of 'using V8 isolate' includes
  * accessing handles or holding onto object pointers obtained
  * from V8 handles while in the particular V8 isolate.  It is up
  * 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
  * (assumes the default isolate that is used if not specified as
  * a parameter for the Locker):
  *
  * \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.
  *   ...
  * } // Destructor called here
  * \endcode
  *
  * If you wish to stop using V8 in a thread A you can do this by either
  * by destroying the v8::Locker object as above or by constructing a
  * v8::Unlocker object:
  *
  * \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.
  *   ...
  * } // Destructor called here.
  * \endcode
  *
  * The Unlocker object is intended for use in a long-running callback
  * from V8, where you want to release the V8 lock for other threads to
  * use.
  *
  * The v8::Locker is a recursive lock.  That is, you can lock more than
  * once in a given thread.  This can be useful if you have code that can
  * be called either from code that holds the lock or from code that does
  * not.  The Unlocker is not recursive so you can not have several
  * Unlockers on the stack at once, and you can not use an Unlocker in a
  * thread that is not inside a Locker's scope.
  *
  * An unlocker will unlock several lockers if it has to and reinstate
  * the correct depth of locking on its destruction. eg.:
  *
  * \code
  * // V8 not locked.
  * {

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

This snippet should use isolate as well.

  *   v8::Locker locker;
  *   // V8 locked.
  *   {
  *     v8::Locker another_locker;
  *     // V8 still locked (2 levels).
  *     {
  *       v8::Unlocker unlocker;
  *       // V8 not locked.
  *     }
  *     // V8 locked again (2 levels).
  *   }
  *   // V8 still locked (1 level).
  * }
  * // V8 Now no longer locked.
  * \endcode
  */

[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();
 
   /**
    * Start preemption.
    *
    * When preemption is started, a timer is fired every n milli seconds
    * that will switch between multiple threads that are in contention
    * for the V8 lock.
    */
   static void StartPreemption(int every_n_ms);
 
   /**
    * Stop preemption.
    */
   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.
    */
   static bool IsActive() { return active_; }
 
  private:
   bool has_lock_;
   bool top_level_;
+  internal::Isolate* isolate_;
 
   static bool active_;
 
   // Disallow copying and assigning.
   Locker(const Locker&);
   void operator=(const Locker&);
 };
 
 
 /**
@@ skipping 548 matching lines @@
 
 
 }  // namespace v8
 
 
 #undef V8EXPORT
 #undef TYPE_CHECK
 
 
 #endif  // V8_H_