[Isolates] Isolate API: first draft.

include/v8.h

Index: include/v8.h
diff --git a/include/v8.h b/include/v8.h
index 02abb4cb0f818fee0a3bbf5b5b85960b002cc3a6..7ce0ddadd0cdd0cee6d9cbf32c5e326c82fdb64a 100644
--- a/include/v8.h
+++ b/include/v8.h
@@ -2385,6 +2385,89 @@ class V8EXPORT HeapStatistics {
 
 
 /**
+ * Isolate represents an isolated instace of the V8 engine.  V8

[Maxim.Mossienko, 2010/07/01 08:31:50]

typo: instace -> instance

[Vitaly Repeshko, 2010/07/01 22:00:57]

Fixed.

+ * isolates have completely separate states.  Objects from one isolate
+ * must not be used in other isolates.  When V8 is initialized a
+ * default isolate is implicitly created and entered.  The embedder
+ * can create additional isolates and use them in parallel in multiple
+ * threads.  An isolate can be entered by at most one thread at any
+ * given time.  The Locker/Unlocker API can be used to synchronize.

[Maxim.Mossienko, 2010/07/01 09:17:02]

This is not currently possible in this API draft. Locker / Unlocker constructor
need to accept Isolate instance to be able to synchronize. 

+ */
+class V8EXPORT Isolate {
+ public:

[Maxim.Mossienko, 2010/07/01 08:31:50]

I think that if we are to preserve API compatibility then many of V8 static
methods should be instance ones in Isolate (e.g. SetFatalErrorHandler, IsDead,
SetCounterFunction, etc).
This would just reflect the fact of Isolate being instance of V8.

+  /**
+   * Stack-allocated class which sets the isolate for all operations
+   * executed within a local scope.
+   */
+  class V8EXPORT Scope {
+   public:
+    explicit Scope(Isolate* isolate) : isolate_(isolate) {
+      isolate->Enter();
+    }
+
+    ~Scope() { isolate_->Exit(); }
+
+   private:
+    Isolate* const isolate_;
+
+    Scope(const Scope&);
+    Scope& operator=(const Scope&);
+  };
+
+  /**
+   * Creates a new isolate.  Does not change the currently entered
+   * isolate.
+   *
+   * When an isolate is no longer used its resources should be freed
+   * by calling Dispose().  Using the delete operator is not allowed.
+   */
+  static Isolate* New();
+
+  /**
+   * Returns the entered isolate for the current thread or NULL in
+   * case there is no current isolate.
+   */
+  static Isolate* GetCurrent();
+
+  /**
+   * Methods below this point require holding a lock in a

[Maxim.Mossienko, 2010/07/01 08:31:50]

IMO bare 'lock' word is confusing in the description (given Locker class
existence), 'caller managed exclusive thread access' is better description

[Vitaly Repeshko, 2010/07/01 22:00:57]

Clarified how the embedder is supposed to hold a lock.

+   * multi-threaded environment.
+   */
+
+  /**
+   * Sets this isolate as the entered one for the current thread.
+   * Saves the previously entered one (if any), so that it can be
+   * restored when exiting.  Re-entering an isolate is allowed.
+   */
+  void Enter();
+
+  /**
+   * Exits this isolate by restoring the previously entered one in the
+   * current thread.  The isolate may still stay the same, if it was
+   * entered more than once.
+   *
+   * Requires: this == Isolate::GetCurrent().
+   */
+  void Exit();
+
+  /**
+   * Disposes the isolate.  The isolate must not be entered by any
+   * thread to be disposable.
+   */
+  void Dispose();
+
+ private:
+
+  Isolate();

[Maxim.Mossienko, 2010/07/01 09:17:02]

Following Locker statics go here:

/**
   * Returns whether v8::Locker is being used by this V8 instance.
   */
bool IsActive() { return active_; }

// Track whether this V8 instance has ever called v8::Locker. This allows the
  // API code to verify that the lock is always held when V8 is being entered.
  bool active_;

+  Isolate(const Isolate&);
+  ~Isolate();
+  Isolate& operator=(const Isolate&);
+  void* operator new(size_t size);
+  void operator delete(void*, size_t);
+};
+
+
+/**
  * Container class for static utility functions.
  */
 class V8EXPORT V8 {