[Isolates] Isolate API: first draft.

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 2367 matching lines @@
   void set_used_heap_size(size_t size) { used_heap_size_ = size; }
 
   size_t total_heap_size_;
   size_t used_heap_size_;
 
   friend class V8;
 };
 
 
 /**
+ * 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 {
  public:
   /** Set the callback to invoke in case of fatal errors. */
   static void SetFatalErrorHandler(FatalErrorCallback that);
 
   /**
    * Ignore out-of-memory exceptions.
    *
@@ skipping 1150 matching lines @@
 
 }  // namespace v8
 
 
 #undef V8EXPORT
 #undef V8EXPORT_INLINE
 #undef TYPE_CHECK
 
 
 #endif  // V8_H_