gin/public/isolate_holder.h

   1 // Copyright 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef GIN_PUBLIC_ISOLATE_HOLDER_H_
   6 #define GIN_PUBLIC_ISOLATE_HOLDER_H_
   7
   8 #include "base/basictypes.h"
   9 #include "base/memory/scoped_ptr.h"
  10 #include "gin/gin_export.h"
  11 #include "gin/public/v8_idle_task_runner.h"
  12 #include "v8/include/v8.h"
  13
  14 namespace gin {
  15
  16 class PerIsolateData;
  17 class RunMicrotasksObserver;
  18 class V8IsolateMemoryDumpProvider;
  19
  20 // To embed Gin, first initialize gin using IsolateHolder::Initialize and then
  21 // create an instance of IsolateHolder to hold the v8::Isolate in which you
  22 // will execute JavaScript. You might wish to subclass IsolateHolder if you
  23 // want to tie more state to the lifetime of the isolate.
  24 class GIN_EXPORT IsolateHolder {
  25  public:
  26   // Controls whether or not V8 should only accept strict mode scripts.
  27   enum ScriptMode {
  28     kNonStrictMode,
  29     kStrictMode
  30   };
  31
  32   // Stores whether the client uses v8::Locker to access the isolate.
  33   enum AccessMode {
  34     kSingleThread,
  35     kUseLocker
  36   };
  37
  38   IsolateHolder();
  39   explicit IsolateHolder(AccessMode access_mode);
  40   ~IsolateHolder();
  41
  42   // Should be invoked once before creating IsolateHolder instances to
  43   // initialize V8 and Gin. In case V8_USE_EXTERNAL_STARTUP_DATA is
  44   // defined, V8's initial natives should be loaded (by calling
  45   // V8Initializer::LoadV8NativesFromFD or
  46   // V8Initializer::LoadV8Natives) before calling this method.  If the
  47   // snapshot file is available, it should also be loaded (by calling
  48   // V8Initializer::LoadV8SnapshotFromFD or
  49   // V8Initializer::LoadV8Snapshot) before calling this method.
  50   static void Initialize(ScriptMode mode,
  51                          v8::ArrayBuffer::Allocator* allocator);
  52
  53   v8::Isolate* isolate() { return isolate_; }
  54
  55   // The implementations of Object.observe() and Promise enqueue v8 Microtasks
  56   // that should be executed just before control is returned to the message
  57   // loop. This method adds a MessageLoop TaskObserver which runs any pending
  58   // Microtasks each time a Task is completed. This method should be called
  59   // once, when a MessageLoop is created and it should be called on the
  60   // MessageLoop's thread.
  61   void AddRunMicrotasksObserver();
  62
  63   // This method should also only be called once, and on the MessageLoop's
  64   // thread.
  65   void RemoveRunMicrotasksObserver();
  66
  67   // This method returns if v8::Locker is needed to access isolate.
  68   AccessMode access_mode() const { return access_mode_; }
  69
  70   void EnableIdleTasks(scoped_ptr<V8IdleTaskRunner> idle_task_runner);
  71
  72   // This method returns V8IsolateMemoryDumpProvider of this isolate, used for
  73   // testing.
  74   V8IsolateMemoryDumpProvider* isolate_memory_dump_provider_for_testing()
  75       const {
  76     return isolate_memory_dump_provider_.get();
  77   }
  78
  79  private:
  80   v8::Isolate* isolate_;
  81   scoped_ptr<PerIsolateData> isolate_data_;
  82   scoped_ptr<RunMicrotasksObserver> task_observer_;
  83   scoped_ptr<V8IsolateMemoryDumpProvider> isolate_memory_dump_provider_;
  84   AccessMode access_mode_;
  85
  86   DISALLOW_COPY_AND_ASSIGN(IsolateHolder);
  87 };
  88
  89 }  // namespace gin
  90
  91 #endif  // GIN_PUBLIC_ISOLATE_HOLDER_H_