节点.js的原生抽象

一个填充了宏和实用性良好的标题文件,用于使Node.js的附加开发在8,10,12,14,16,17,18,19,20,21,22,23,24和25版本之间更容易.

目前版本: 2.26.2

(见 变动情况 用于完整更改日志)

由于V8(也有一些在节点核心)的疯狂变化,保持了各版本的本地加通编译,特别是0.10至0.12至4.0,是一个轻微的噩梦. 该项目的目标是储存开发本地节点的所有必要逻辑,而无需检查 NODE_MODULE_VERSION 并让自己进入一个宏观角.

该项目还包含一些使附加开发更加愉快的辅助设施.

• 新闻更新( U)
• 使用量
• 示例
• API 密码
• 测试
• 已知问题
• 治理和贡献

新闻更新( U)

使用量

简单添加 南语 使用 npm 、 纱线 或 bun 等软件包管理器作为依赖:

$ npm install nan

拉入通往 南语 在你身边 装订.gyp 这样你就可以使用 #include <nan.h> 在你身边 页:1 文件 :

"include_dirs" : [
    "<!(node -e \"require('nan')\")"
]

这就像一个 -I<path-to-NAN> 当编译你的附加.

示例

刚开始跟小楠谈? 看看这个 节点添加实例。 。 。 .

参见a 快速启动 阿南,你来干什么 沸腾 利用南语基本功能的现成项目.

比较简单的例子是: aync pi 估计示例 在完整代码的示例目录中,并解释这个Monte Carlo Pi 估计例子的作用。 下面只是整个例子的一些部分,说明如何使用 南语。 。 。 .

还有一个例子是 南- 实例- eol。它显示新线检测作为本地加通执行.

也看看我们的全面 C++ 测试套件 它有很多代码片段 用于你的粘贴乐趣.

API 密码

除以下无线网络文件外,请参考:

• V8 启动指南
• V8 API 文档
• 节点添加文档

JavaScript 可访问方法

A 类 模板 是上下文中JavaScript函数和对象的蓝图。 您可以使用一个模板来将 C++ 函数和数据结构包裹在 JavaScript 对象内部,以便它们可以从 JavaScript 中被操纵. 见V8嵌入器指南关于 模板 以供参考.

为了通过模板向JavaScript显示功能,您必须以能理解的形式向V8提供. 在NAN支持的V8版本中,JavaScript-可访问方法签名差异很大,NAN完全摘要方法声明,并为您提供了类似于最新V8 API的界面,但后向兼容的更古老版本仍然使用现在已逝去的 v8::Argument 类型.

• 方法参数类型

• Nan::FunctionCallbackInfo
• Nan::PropertyCallbackInfo
• Nan::ReturnValue

• 方法声明

• 方法声明
• 获取声明
• 正式声明
• 财产获取器声明
• 财产设定申报
• 财产登记人声明
• 财产删除器声明
• 财产查询声明
• 索引获取器声明
• 索引设置声明
• 索引计数器声明
• 索引删除器声明
• 索引查询声明

• 方法和模板助手

• Nan::SetMethod()
• Nan::SetPrototypeMethod()
• Nan::SetAccessor()
• Nan::SetNamedPropertyHandler()
• Nan::SetIndexedPropertyHandler()
• Nan::SetTemplate()
• Nan::SetPrototypeTemplate()
• Nan::SetInstanceTemplate()
• Nan::SetCallHandler()
• Nan::SetCallAsFunctionHandler()

范围

A 类 本地控点 是对象的指针。 所有V8物体都使用手柄访问,由于V8垃圾收集器的工作方式,它们是必要的.

一个手柄范围可以被认为是任何数量的手柄的容器. 当你完成了手柄, 而不是逐个删除, 你可以简单地删除它们的范围.

创建 HandleScope 对象在支持的 V8 版本中不同 。 因此,NAN提供了自己的实施,可以安全地在这些方面使用.

• Nan::HandleScope
• Nan::EscapableHandleScope

另见V8嵌入器指南关于 处理和垃圾收集。 。 。 .

持续参考

独立于任意的对象引用 HandleScope 是一个 持久性 参考文献。 在一个 Local 操作只活到 HandleScope 资源分配情况a Persistent 手柄在明确处理之前仍然有效.

由于V8 API的演化,NAN有必要提供该软件的包装执行 Persistent 分类以提供跨V8版本的兼容性.

• Nan::PersistentBase & v8::PersistentBase
• Nan::NonCopyablePersistentTraits & v8::NonCopyablePersistentTraits
• Nan::CopyablePersistentTraits & v8::CopyablePersistentTraits
• Nan::Persistent
• Nan::Global
• Nan::WeakCallbackInfo
• Nan::WeakCallbackType

另见V8嵌入器指南关于 处理和垃圾收集。 。 。 .

新设

NAN提供 Nan::New() 帮助创建新的 JavaScript 对象,其方式可以兼容所有支持的版本的 V8.

• Nan::New()
• Nan::Undefined()
• Nan::Null()
• Nan::True()
• Nan::False()
• Nan::EmptyString()

转换器

NAN 包含转换函数 v8::Values 到其他地点 v8::Value 类型和本地类型。 由于类型转换不能保证成功,所以会返回 Nan::Maybe 类型。 这些转换器可用于替换 value->ToX() 财务报告和审定财务报表 value->XValue() (何处) X 是一类,例如:. Boolean)的方式提供了贯穿V8版本的一致界面. 更新版本的 V8 使用新的 v8::Maybe 财务报告和审定财务报表 v8::MaybeLocal 用于这些转换的类型,旧版本没有这种功能,所以由NAN提供.

• Nan::To()

可能的类型

这个 Nan::MaybeLocal 财务报告和审定财务报表 Nan::Maybe 类型是封装的monads v8::Local 处理 可能为空。 。 。 .

• 可能的类型
  • Nan::MaybeLocal
  • Nan::Maybe
  • Nan::Nothing
  • Nan::Just
• 也许是帮手
  • Nan::Call()
  • Nan::ToDetailString()
  • Nan::ToArrayIndex()
  • Nan::Equals()
  • Nan::NewInstance()
  • Nan::GetFunction()
  • Nan::Set()
  • Nan::DefineOwnProperty()
  • Nan::ForceSet()
  • Nan::Get()
  • Nan::GetPropertyAttributes()
  • Nan::Has()
  • Nan::Delete()
  • Nan::GetPropertyNames()
  • Nan::GetOwnPropertyNames()
  • Nan::SetPrototype()
  • Nan::ObjectProtoToString()
  • Nan::HasOwnProperty()
  • Nan::HasRealNamedProperty()
  • Nan::HasRealIndexedProperty()
  • Nan::HasRealNamedCallbackProperty()
  • Nan::GetRealNamedPropertyInPrototypeChain()
  • Nan::GetRealNamedProperty()
  • Nan::CallAsFunction()
  • Nan::CallAsConstructor()
  • Nan::GetSourceLine()
  • Nan::GetLineNumber()
  • Nan::GetStartColumn()
  • Nan::GetEndColumn()
  • Nan::CloneElementAt()
  • Nan::HasPrivate()
  • Nan::GetPrivate()
  • Nan::SetPrivate()
  • Nan::DeletePrivate()
  • Nan::MakeMaybe()

脚本

NAN 提供 v8::Script 作为API的帮助者在支持版本的V8上有所改变.

• Nan::CompileScript()
• Nan::RunScript()
• Nan::ScriptOrigin

贾森

这个 贾森 对象提供了 C++ 版本的方法 JSON 对象。 V8通过 v8::JSON 对象.

• Nan::JSON.Parse
• Nan::JSON.Stringify

参考 V8文档 关于这些方法及其论据的更多信息.

错误

NAN包括用于创建,抛出和抓取错误的帮助者,因为这些功能在支持的V8版本中有很多不同,必须被抽象.

注意,错误对象只是一种特殊形式: v8::Value。 。 。 .

并参看V8嵌入器指南关于 例外 更多信息.

• Nan::Error()
• Nan::RangeError()
• Nan::ReferenceError()
• Nan::SyntaxError()
• Nan::TypeError()
• Nan::ThrowError()
• Nan::ThrowRangeError()
• Nan::ThrowReferenceError()
• Nan::ThrowSyntaxError()
• Nan::ThrowTypeError()
• Nan::FatalException()
• Nan::ErrnoException()
• Nan::TryCatch

缓冲

纳恩的 node::Buffer 随着API在所支持的节点版本中更改而存在帮助者. 使用这些方法确保兼容性.

• Nan::NewBuffer()
• Nan::CopyBuffer()
• Nan::FreeCallback()

南:回话

Nan::Callback 更方便使用 v8::Function 以调用方式处理。 包起来的类 v8::Function 手柄,保护它不受垃圾收集的影响,使其在同步执行过程中对存储和使用特别有用.

• Nan::Callback

同步工作助手

Nan::AsyncWorker, (中文(简体) ), Nan::AsyncProgressWorker 财务报告和审定财务报表 Nan::AsyncProgressQueueWorker 是帮助课,使使用同步代码的工作更容易.

• Nan::AsyncWorker
• Nan::AsyncProgressWorkerBase & Nan::AsyncProgressWorker
• Nan::AsyncProgressQueueWorker
• Nan::AsyncQueueWorker

字符串和字节

杂项字符串和字节编码及解码功能为所支持的V8和节点版本提供了兼容性. 由NAN执行,以确保所有编码类型都得到支持,甚至对于缺失的更古老的节点版本.

• Nan::Encoding
• Nan::Encode()
• Nan::TryEncode()
• Nan::DecodeBytes()
• Nan::DecodeWrite()

对象包装器

这个 ObjectWrap 类可以用来制作被包裹的C++对象和被包裹对象的工厂.

• Nan::ObjectWrap

V8 内部

进入V8内部的钩子——包括GC和统计——在支持的V8版本中不同,因此NAN提供了自己的钩子,称之为适当的V8方法.

• NAN_GC_CALLBACK()
• Nan::AddGCEpilogueCallback()
• Nan::RemoveGCEpilogueCallback()
• Nan::AddGCPrologueCallback()
• Nan::RemoveGCPrologueCallback()
• Nan::GetHeapStatistics()
• Nan::SetCounterFunction()
• Nan::SetCreateHistogramFunction()
• Nan::SetAddHistogramSampleFunction()
• Nan::IdleNotification()
• Nan::LowMemoryNotification()
• Nan::ContextDisposedNotification()
• Nan::GetInternalFieldPointer()
• Nan::SetInternalFieldPointer()
• Nan::AdjustExternalMemory()

杂项 V8 助手

• Nan::Utf8String
• Nan::GetCurrentContext()
• Nan::SetIsolateData()
• Nan::GetIsolateData()
• Nan::TypedArrayContents

杂项节点帮助

• Nan::AsyncResource
• Nan::MakeCallback()
• NAN_MODULE_INIT()
• Nan::Export()

测试

运行 NAN 测试是:

npm install
npm run-script rebuild-tests
npm test

或者只是说:

npm install
make test

已知问题

与OSX上的0.12节点相接

在OSX上有了足够多的新编译器,V8头与Node.js0.12对应的版本 不再编译。 此错误看起来类似 :

❯   CXX(target) Release/obj.target/accessors/cpp/accessors.o
In file included from ../cpp/accessors.cpp:9:
In file included from ../../nan.h:51:
In file included from /Users/ofrobots/.node-gyp/0.12.18/include/node/node.h:61:
/Users/ofrobots/.node-gyp/0.12.18/include/node/v8.h:5800:54: error: 'CreateHandle' is a protected member of 'v8::HandleScope'
  return Handle<T>(reinterpret_cast<T*>(HandleScope::CreateHandle(
                                        ~~~~~~~~~~~~~^~~~~~~~~~~~

这可以通过补丁您本地版本的 v8. h 来工作 v8::Handle 一个朋友 v8::HandleScope。既然两个节点.js 都不再支持此放行 此补丁不能由任一工程在正式发布时发布 .

出于这个原因,我们并不在这个项目的CI中测试OSX上的Node.js0.12. 如果您需要支持的话 该配置, 您需要获得一个更旧的编译器, 或者对版本应用源补丁 v8头作为工作.

治理和贡献

NAN 受 节点.js Addon API工作组

Addon API工作组(工作组)

NAN项目由一个工作组共同管理,该工作组负责该项目的高级别指导.

工作组成员也被称为"合作者",两者没有区别,不同于其他Node.js项目.

工作组对该项目拥有最终权力,包括:

• 技术方向
• 项目治理和进程(包括本政策)
• 捐款政策
• GitHub 寄存器托管
• 保留其他合作者名单

目前工作组成员名单见项目 读取。 。 。 .

做出重要而有价值贡献的个人是工作组成员,他们承诺参与该项目。 这些人由工作组确定,他们加入工作组是通过GitHub讨论的,要求参加讨论的工作组成员以接受表决所需的工作组50%的法定人数达成共识.

说明: 如果您做出了重大贡献,且不被视为承诺获取日志,则会直接与工作组成员联系.

工作组成员/合作者的现有名单见项目 读取。 。 。 .

寻求共识的进程

工作组接下来是: 寻求共识 决策模式.

NAN寄存处内容的修改是在合作的基础上进行的. 任何拥有GitHub账户的人均可通过拉动请求提出修改建议,并由工作组审议。 所有拉动请求都必须由具备足够专门知识的工作组成员审查和接受,该成员能够对改变负起全部责任。 如果现有工作组成员提出拉票请求,则需再增加一名工作组成员方可签字。 如果增加工作组的成员参加,而且对某项修改意见不一,应寻求协商一致.

如果修改提案无法达成协商一致,工作组成员可要求工作组成员进行表决。 简单多数胜出.

开发者原产地证书 1.1

通过对该项目作出贡献,我证明:

• (a) 该捐款全部或部分由我和本人创造 有权以开源许可证提交 (一) 在档案中注明;或

• (b) 贡献以以往工作为基础,即: 根据我的知识, 在一个适当的公开源码之下 我有权根据许可证提交 进行修改的工作,无论是全部或部分 由我,在同一开源许可证(除非我是) 如前所述,允许以不同许可证提交来文 在文件中;或

• (c) 捐款由其他一些人直接提供 (a)、(b)或(c)的认证人和我 这个.

• (d) 我理解并同意这个项目和贡献 捐款记录(包括所有 我随即提交个人信息,包括我的签注) 无限期保留,并可按照 此项目或所涉及的开源许可证.

工作组成员/合作者

许可证和版权

版权 (c) 2018 NAN WG成员/合作者(上列).

为Node.js开发的原生文摘凭麻省理工学院的许可证。 麻省理工学院许可证中未明确授予的所有权利均予保留。 详见包含的LICENSE文件.