neon

Module sys

source
Available on crate feature sys only.
Expand description

Raw bindings to Node-API

Node-API is Node.js’s API for building native addons. Neon is predominantly a safe wrapper for Node-API and most users should prefer the the high level abstractions outside of the sys module.

However, directly using Node-API can be a useful tool for accessing low level functionality not exposed by Neon or experimenting with extensions to Neon without needing to fork the project.

§Initialization

Before any Node-API functions may be used, setup must be called at least once.

unsafe { neon::sys::setup(env); }

Note: It is unnecessary to call setup if #[neon::main] is used to initialize the addon.

§Safety

The following are guidelines for ensuring safe usage of Node-API in Neon but, do not represent a comprehensive set of safety rules. If possible, users should avoid calling Neon methods or holding references to structures created by Neon when calling Node-API functions directly.

§Env

Neon ensures safety by carefully restricting access to Env by wrapping it in a Context. Usages of Env should follow Neon’s borrowing rules of Context.

It is unsound to use an Env if Rust’s borrowing rules would prevent usage of the in scope Context.

§Values

Neon value types encapsulate references to JavaScript values with a known type. It is unsound to construct a Neon value with a Value of the incorrect type.

§Example

use neon::{context::Cx, prelude::*, sys::bindings};

let cx = unsafe {
    neon::sys::setup(env);

    Cx::from_raw(env)
};

let raw_string: bindings::Value = cx.string("Hello, World!").to_raw();
let js_string = unsafe { JsString::from_raw(&cx, raw_string) };

Modules§

  • FFI bindings to Node-API symbols

Functions§

  • Loads Node-API symbols from the host process.