[译] V8 使用者文档

摘要：注意句柄栈并不是调用栈中的一部分，但句柄域却在栈中。一个依赖于构造函数和析构函数来管理下层对象的生命周期。对象模板用来配置将这个函数作为构造函数而创建的对象。

如果你已经阅读过了上手指南，那么你已经知道了如何作为一个多带带的虚拟机使用 V8 ，并且熟悉了一些 V8 中的关键概念，如句柄，域 和上下文。在本文档中，还将继续深入讨论这些概念并且介绍其他一些在你的 C++ 应用中使用 V8 的关键点。

V8 的 API 提供了编译和执行脚本，访问 C++ 方法和数据结构，处理错误和启用安全检查的函数。你的应用可以像使用其他的 C++ 库一样使用 V8 。你的 C++ 应用可以通过引入头文件 include/v8.h 来访问 V8 API 。

当你想要优化你的应用时，V8 设计概要文档可以提供很多有用的背景知识。

这篇文档的受众是那些想要在自己的 C++ 程序中使用 V8 JavaScript 引擎的人。它将能帮助你在 JavaScript 中使用你应用中的 C++ 对象和方法，亦能帮助你在 C++ 应用中使用 JavaScript 对象和方法。

一个句柄提供了对在堆中的一个 JavaScript 对象地址的引用。V8 的垃圾回收器会在该对象不能再次被访问到时，将其回收。在垃圾回收的过程中，垃圾回收器可能会改变对象在堆中的位置。当垃圾回收器移动对象时，所有引用到该对象的句柄也会被一同更新。

当一个对象在 JavaScript 中已经不可被访问并且没有任何指向它的句柄时，它就会被垃圾回收。V8 的垃圾回收机制是 V8 性能表现的关键。更多信息可参阅 V8 设计概要文档。

句柄分为许多种：

本地句柄会被分配在栈中，并且当对应的析构函数被调用时，它也会被删除。这些本地句柄的生命周期取决于它对应的句柄域（handle scope），句柄域通常在一个函数调用的开始被创建。当句柄域被删除时，垃圾回收器就可以清除之前分配在该句柄域中的所有句柄了，因为它们不能再被 JavaScript 或其他句柄所访问到。这也正是在上手指南中使用的句柄。
本地句柄可通过类 Local 创建。

注意：句柄栈并不是 C++ 调用栈中的一部分，但句柄域却在 C++ 栈中。故句柄域不可通过 new 关键字来分配。

持久句柄提供了对分配在堆中的 JavaScript 对象的引用。当你需要在超过一次函数中保持对一个对象的引用时，或者句柄的生命周期与 C++ 的块级域不相符时，你应使用持久句柄。例如，在 Google Chrome 中，持久句柄被用来引用 DOM 节点。一个持久句柄可以通过 PersistentBase::SetWeak ，变为弱（weak）持久句柄，当一个对象所剩的唯一引用是来自于一个弱持久句柄时，便会触发垃圾回收。

一个 UniquePersistent 依赖于 C++ 构造函数和析构函数来管理下层对象的生命周期。

一个 Persistent 可以通过自身的构造函数来创建，但必须手动地通过 Persistent::Reset 来清除。

还有两种很少会被使用到的句柄，在这里我们仅对它们做一个简单的介绍：

永久（Eternal）句柄是一种为被认为永远不会被删除的 JavaScript 对象所设计的持久句柄。它的创建开销更低，因为它不需要被垃圾回收。

Persistent 和 UniquePersistent 都不能被复制，所以它们不能作为 C++ 11 之前的标准库容器中的值来使用。PersistentValueMap 和 PersistentValueVector 为它们提供了容器类，提供了类似于集合和向量的语义。

当然，每当你为了创建一个对象而创建一个本地句柄时，往往可能会导致创建了许多句柄。这就是句柄域所存在的意义。你可以将句柄域视作一个保存了许多句柄的容器。当句柄域的析构函数被调用时，所有它里面的句柄都会被从栈中移除。正如你所期望的，这些句柄做指向的对象随后就可以被垃圾回收。

回到我们在上手指南中的例子，在下面的图示中，你可以看到句柄栈和堆中的对象。值得注意的是，Context::New() 的返回值是一个本地句柄，然后我们基于它创建了一个新的持久句柄，用以阐述持久句柄的用途。

当 HandleScope::~HandleScope 析构函数被调用时，该句柄域便会被删除。所有被句柄域中的句柄所引用的对象，都将可以在下次垃圾回收时被删除，如果没有其他对于它们的引用存在。垃圾回收器同样还会删除堆中的 source_obj 和 script_obj 对象，因为它们不被任何句柄所引用，并且也不可被 JavaScript 访问。由于 context 对象是一个持久句柄，所以当句柄域退出时，它并不会被移除，唯一可以删除它的办法就是调用它的 Reset 方法。

注意：后文中的句柄如果不加注明，都指的是本地句柄。

在这个模型下，有一个非常常见的陷阱需要注意：你不可以直接地在一个声明了句柄域的函数中返回一个本地句柄。如果你这么做了，那么你试图返回的本地句柄，将会在函数返回之前，在句柄域的析构函数中被删除。正确的做法是使用 EscapableHandleScope 来代替 HandleScope 创建句柄域，然后调用 Escape 方法，并且传入你想要返回的句柄。例子：

// 这个函数会返回一个带有 x，y 和 z 三个元素的新数组
Local NewPointArray(int x, int y, int z) {
  v8::Isolate* isolate = v8::Isolate::GetCurrent();

  // 我们将会创建一些临时的句柄，所以我们先创建一个句柄域
  EscapableHandleScope handle_scope(isolate);

  // 创建一个空数组
  Local array = Array::New(isolate, 3);

  // 如果在创建数组时产生异常，则返回一个空数组
  if (array.IsEmpty())
    return Local();

  // 填充数组
  array->Set(0, Integer::New(isolate, x));
  array->Set(1, Integer::New(isolate, y));
  array->Set(2, Integer::New(isolate, z));

  // 通过 Escape 返回该数组
  return handle_scope.Escape(array);
}

Escape 方法复制参数中的值至一个封闭的域中，然后删除其他本地句柄，最后返回这个可以被安全返回的新句柄副本。

在 V8 中，上下文是一个允许多个分别独立的，不相关的 JavaScript 应用在一个多带带的 V8 实例中运行的执行环境。你必须为每一个你想要执行的 JavaScript 代码指定一个上下文。

这样做是必要的么？这么做的原因是，JavaScript 本身提供了一组内建的工具函数和对象，但它们又可以被 JavaScript 代码所修改。例如，两个完全没有关联的 JavaScript 函数同时修改了一个全局对象，那么可能就会造成不可预期的后果。

从 CPU 时间和内存的角度来看，创建一个拥有指定数量的内建对象的执行上下文似乎开销很大。但是，V8 的缓存机制可以确保，虽然创建的第一个上下文开销非常大，但后续的上下文创建的开销都会小很多。这是因为第一次创建上下文时，需要创建内建对象和解析内建的 JavaScript 代码，而后续的上下文创建则只需为它们的上下文创建内建对象即可。如果开启了 V8 的快照特性（可通过选项 snapshot=yes 开启，默认值即为开启），第一次创建上下文的时间花销也会被极大的优化，因为快照中包含了这些所需的内建 JavaScript 代码已然被编译后的版本。除了垃圾回收外，V8 的缓存也是 V8 性能表现的关键，更多详情可参阅V8 设计概要文档。

当你创建了一个上下文后，你可以随意地进入和离开它，没有次数的限制。当你已经在上下文 A 中时，你还可以再次进入另一个上下文 B ，这以为着当前的上下文环境变成了 B 。当你离开了 B 后，A 就再次成为了当前上下文。如图示：

需要注意的是，JavaScript 内建工具函数和对象是相互独立的。当你创建一个上下文时，你可以同时设置可选的安全标识（security token）。更多详情请参阅下文的安全模型章节。

在 V8 中使用上下文的最初动机是，在一个浏览器中，每一个窗口和 iframe 都需要有各自独立的 JavaScript 环境。

一个模板即为一个上下文中 JavaScript 函数和对象的蓝图。你可以在 JavaScript 对象内使用一个模板来包裹 C++ 函数和数据结构，致使它们可以被 JavaScript 脚本所操纵。例如，Google Chrome 使用模板来将 C++ DOM 节点包裹为 JavaScript 对象，然后在全局命名空间下注册函数。你可以创建一个模板集合，然后在不同的上下文中使用它。模板的数量并没有限制，但是在一个指定的上下文中，每一个模板都只允许有一个它的实例。

在 JavaScript 中，函数和对象间有强烈的二元性。在 Java 或 C++ 中，如果要创建一个新类型的对象，你需要首先定义一个新的类。而在 JavaScript 中，你需要定义一个新的函数，然后把这个函数视作一个构造函数。一个 JavaScript 对象的外形和功能都与它的构造函数关系密切。这些也都反应在了 V8 模板的工作方式中。模板分为两种类型：

函数模板
一个函数模板就是一个独立函数的蓝图。在一个你想要实例化 JavaScript 函数的上下文中，你可以通过调用模板的 GetFunction 方法来创建一个模板的 JavaScript 实例。当 JavaScript 函数实例被调用时，你还可以为模板关联一个 C++ 回调函数一同被调用。

对象模板
每一个函数模板都有一个与之关联的对象模板。对象模板用来配置将这个函数作为构造函数而创建的对象。你可以为对象模板关联两种类型的 C++ 回调：

访问器回调会在指定对象原型被脚本访问时被调用。

拦截器回调会在任何对象原型被脚本访问时被调用。

访问器和拦截器的详情会在后文中继续讨论。

下面的例子中，我们将创建一个关联全局对象的模板，然后设置一些内建的全局函数。

// 创建一个关联全局对象的模板，然后设置一些内建的全局函数。
Local global = ObjectTemplate::New(isolate);
global->Set(String::NewFromUtf8(isolate, "log"), FunctionTemplate::New(isolate, LogCallback));

Persistent context = Context::New(isolate, NULL, global);

该例子取自于 process.cc 中的 JsHttpProcessor::Initialiser。

访问器为当一个 JavaScript 对象原型被脚本访问时，执行的一个 C++ 回调函数，它计算并返回一个值。访问器需要通过一个对象模板来配置，通过它的 SetAccessor 方法。这个方法的第一个参数为关联的属性，最后一个参数为当脚本试图读写这个属性时执行的回调。

访问的复杂度取决于你想要其控制的数据类型：

访问静态全局变量

访问动态变量

假设有两个名为 x 和 y 的 C++ 整形变量，它们需要成为一个上下文的 JavaScript 中的全局变量。为了达成这个目的，当脚本读或写这些变量时，你需要调用 C++ 访问器函数。这些访问器函数使用 Integer::New 来把 C++ 整形数转换为 JavaScript 整形数，并且使用 Int32Value 来把 JavaScript 整形数转换为 C++ 整形数。例子：

  void XGetter(Local property,
                const PropertyCallbackInfo& info) {
    info.GetReturnValue().Set(x);
  }

  void XSetter(Local property, Local value,
               const PropertyCallbackInfo& info) {
    x = value->Int32Value();
  }

  // YGetter/YSetter 十分类似，这里就省略了

  Local global_templ = ObjectTemplate::New(isolate);
  global_templ->SetAccessor(String::NewFromUtf8(isolate, "x"), XGetter, XSetter);
  global_templ->SetAccessor(String::NewFromUtf8(isolate, "y"), YGetter, YSetter);
  Persistent context = Context::New(isolate, NULL, global_templ);

注意代码中的对象模板和上下文几乎在同时创建。模板可以提前创建好，然后在任意数量的上下文中使用它。

在上面的例子中，变量是静态和全局的。那么，如果数据是动态的，像浏览器中的 DOM 树这样呢？假设我们有一个 C++ 类 Point，它有两个属性 x 和 y：

  class Point {
   public:
    Point(int x, int y) : x_(x), y_(y) { }
    int x_, y_;
  }

为了让任意数量的 C++ point 实例可以通过 JavaScript 访问，我们需要为每一个 C++ point 实例创建一个 JavaScript 对象。这可以通过外部（external）值和内部（internal）属性共同办到。

首先创建一个对象模板，用以包裹 point 实例：

  Local point_templ = ObjectTemplate::New(isolate);

每一个 JavaScript 中的 point 对象都保持了对 C++ 对象的引用，因为它以内部属性的方式被包裹。这些属性不可通过 JavaScript 访问，只能通过 C++ 代码访问到。一个对象可以有任意数量的内部属性，这个数量需通过以下方法来设置：

  point_templ->SetInternalFieldCount(1);

上面的例子中，内部属性的数量被设置为了 1，表明这对象有一个内部属性，索引值为 0。

向模板添加 x 和 y 访问器：

  point_templ.SetAccessor(String::NewFromUtf8(isolate, "x"), GetPointX, SetPointX);
  point_templ.SetAccessor(String::NewFromUtf8(isolate, "y"), GetPointY, SetPointY);

接下来，我们通过创建一个新的模板实例来包裹 C++ point 实例，然后将内部属性 0 设置为 p 的外部包裹。

  Point* p = ...;
  Local