naskya/napi-rs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs: rust doc enhancement

Browse source
This commit is contained in:
LongYinan 2020-12-22 21:32:50 +08:00
parent db930dabe7
commit 5869e04283
No known key found for this signature in database
GPG key ID: C3666B7FC82ADAD7
2 changed files with 46 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

65
napi/src/env.rs
View file

@ -37,10 +37,13 @@ pub type Callback = extern "C" fn(sys::napi_env, sys::napi_callback_info) -> sys
#[derive(Clone, Copy)] #[derive(Clone, Copy)]
/// `Env` is used to represent a context that the underlying N-API implementation can use to persist VM-specific state. /// `Env` is used to represent a context that the underlying N-API implementation can use to persist VM-specific state.
/// This structure is passed to native functions when they're invoked, and it must be passed back when making N-API calls. ///
/// Specifically, the same `Env` that was passed in when the initial native function was called must be passed to any subsequent nested N-API calls. /// Specifically, the same `Env` that was passed in when the initial native function was called must be passed to any subsequent nested N-API calls.
///
/// Caching the `Env` for the purpose of general reuse, and passing the `Env` between instances of the same addon running on different Worker threads is not allowed. /// Caching the `Env` for the purpose of general reuse, and passing the `Env` between instances of the same addon running on different Worker threads is not allowed.
///
/// The `Env` becomes invalid when an instance of a native addon is unloaded. /// The `Env` becomes invalid when an instance of a native addon is unloaded.
///
/// Notification of this event is delivered through the callbacks given to `Env::add_env_cleanup_hook` and `Env::set_instance_data`. /// Notification of this event is delivered through the callbacks given to `Env::add_env_cleanup_hook` and `Env::set_instance_data`.
pub struct Env(pub(crate) sys::napi_env); pub struct Env(pub(crate) sys::napi_env);
@ -52,6 +55,7 @@ impl Env {
} }
#[inline] #[inline]
/// Get [JsUndefined](./struct.JsUndefined.html) value
pub fn get_undefined(&self) -> Result<JsUndefined> { pub fn get_undefined(&self) -> Result<JsUndefined> {
let mut raw_value = ptr::null_mut(); let mut raw_value = ptr::null_mut();
check_status!(unsafe { sys::napi_get_undefined(self.0, &mut raw_value) })?; check_status!(unsafe { sys::napi_get_undefined(self.0, &mut raw_value) })?;
@ -145,6 +149,7 @@ impl Env {
} }
/// [n_api_napi_create_bigint_words](https://nodejs.org/api/n-api.html#n_api_napi_create_bigint_words) /// [n_api_napi_create_bigint_words](https://nodejs.org/api/n-api.html#n_api_napi_create_bigint_words)
///
/// The resulting BigInt will be negative when sign_bit is true. /// The resulting BigInt will be negative when sign_bit is true.
#[cfg(feature = "napi6")] #[cfg(feature = "napi6")]
#[inline] #[inline]
@ -282,6 +287,7 @@ impl Env {
#[inline] #[inline]
/// This API allocates a node::Buffer object and initializes it with data backed by the passed in buffer. /// This API allocates a node::Buffer object and initializes it with data backed by the passed in buffer.
///
/// While this is still a fully-supported data structure, in most cases using a TypedArray will suffice. /// While this is still a fully-supported data structure, in most cases using a TypedArray will suffice.
pub fn create_buffer_with_data(&self, mut data: Vec<u8>) -> Result<JsBufferValue> { pub fn create_buffer_with_data(&self, mut data: Vec<u8>) -> Result<JsBufferValue> {
let length = data.len(); let length = data.len();
@ -309,9 +315,7 @@ impl Env {
#[inline] #[inline]
/// # Safety /// # Safety
/// Mostly same with `create_buffer_with_data`, but you must ensure data will be dropped **after** the `Buffer` is been GC. /// Mostly the same with `create_buffer_with_data`, but you must ensure data will be dropped **after** the `Buffer` has been GC.
///
/// And should manually trigger `Env::adjust_external_memory` after data is dropped.
pub unsafe fn create_buffer_with_manually_drop_data(&self, data: &[u8]) -> Result<JsBufferValue> { pub unsafe fn create_buffer_with_manually_drop_data(&self, data: &[u8]) -> Result<JsBufferValue> {
let length = data.len(); let length = data.len();
let mut raw_value = ptr::null_mut(); let mut raw_value = ptr::null_mut();
@ -324,12 +328,6 @@ impl Env {
ptr::null_mut(), ptr::null_mut(),
&mut raw_value, &mut raw_value,
))?; ))?;
let mut changed = 0;
check_status!(sys::napi_adjust_external_memory(
self.0,
length as i64,
&mut changed
))?;
Ok(JsBufferValue::new( Ok(JsBufferValue::new(
JsBuffer(Value { JsBuffer(Value {
env: self.0, env: self.0,
@ -354,6 +352,7 @@ impl Env {
#[inline] #[inline]
/// This API allocates a node::Buffer object and initializes it with data copied from the passed-in buffer. /// This API allocates a node::Buffer object and initializes it with data copied from the passed-in buffer.
///
/// While this is still a fully-supported data structure, in most cases using a TypedArray will suffice. /// While this is still a fully-supported data structure, in most cases using a TypedArray will suffice.
pub fn create_buffer_copy<D>(&self, data_to_copy: D) -> Result<JsBufferValue> pub fn create_buffer_copy<D>(&self, data_to_copy: D) -> Result<JsBufferValue>
where where
@ -425,8 +424,11 @@ impl Env {
#[inline] #[inline]
/// This API allows an add-on author to create a function object in native code. /// This API allows an add-on author to create a function object in native code.
///
/// This is the primary mechanism to allow calling into the add-on's native code from JavaScript. /// This is the primary mechanism to allow calling into the add-on's native code from JavaScript.
///
/// The newly created function is not automatically visible from script after this call. /// The newly created function is not automatically visible from script after this call.
///
/// Instead, a property must be explicitly set on any object that is visible to JavaScript, in order for the function to be accessible from script. /// Instead, a property must be explicitly set on any object that is visible to JavaScript, in order for the function to be accessible from script.
pub fn create_function(&self, name: &str, callback: Callback) -> Result<JsFunction> { pub fn create_function(&self, name: &str, callback: Callback) -> Result<JsFunction> {
let mut raw_result = ptr::null_mut(); let mut raw_result = ptr::null_mut();
@ -448,8 +450,11 @@ impl Env {
#[inline] #[inline]
/// This API retrieves a napi_extended_error_info structure with information about the last error that occurred. /// This API retrieves a napi_extended_error_info structure with information about the last error that occurred.
///
/// The content of the napi_extended_error_info returned is only valid up until an n-api function is called on the same env. /// The content of the napi_extended_error_info returned is only valid up until an n-api function is called on the same env.
///
/// Do not rely on the content or format of any of the extended information as it is not subject to SemVer and may change at any time. It is intended only for logging purposes. /// Do not rely on the content or format of any of the extended information as it is not subject to SemVer and may change at any time. It is intended only for logging purposes.
///
/// This API can be called even if there is a pending JavaScript exception. /// This API can be called even if there is a pending JavaScript exception.
pub fn get_last_error_info(&self) -> Result<ExtendedErrorInfo> { pub fn get_last_error_info(&self) -> Result<ExtendedErrorInfo> {
let mut raw_extended_error = ptr::null(); let mut raw_extended_error = ptr::null();
@ -505,6 +510,7 @@ impl Env {
#[inline] #[inline]
#[allow(clippy::expect_fun_call)] #[allow(clippy::expect_fun_call)]
/// In the event of an unrecoverable error in a native module /// In the event of an unrecoverable error in a native module
///
/// A fatal error can be thrown to immediately terminate the process. /// A fatal error can be thrown to immediately terminate the process.
pub fn fatal_error(self, location: &str, message: &str) { pub fn fatal_error(self, location: &str, message: &str) {
let location_len = location.len(); let location_len = location.len();
@ -527,6 +533,7 @@ impl Env {
#[cfg(feature = "napi3")] #[cfg(feature = "napi3")]
#[inline] #[inline]
/// Trigger an 'uncaughtException' in JavaScript. /// Trigger an 'uncaughtException' in JavaScript.
///
/// Useful if an async callback throws an exception with no way to recover. /// Useful if an async callback throws an exception with no way to recover.
pub fn fatal_exception(&self, err: Error) { pub fn fatal_exception(&self, err: Error) {
unsafe { unsafe {
@ -536,6 +543,7 @@ impl Env {
} }
#[inline] #[inline]
/// Create JavaScript class
pub fn define_class( pub fn define_class(
&self, &self,
name: &str, name: &str,
@ -649,6 +657,7 @@ impl Env {
#[inline] #[inline]
/// Get reference value from `Ref` with type check /// Get reference value from `Ref` with type check
///
/// Return error if the type of `reference` provided is mismatched with `T` /// Return error if the type of `reference` provided is mismatched with `T`
pub fn get_reference_value<T>(&self, reference: &Ref<()>) -> Result<T> pub fn get_reference_value<T>(&self, reference: &Ref<()>) -> Result<T>
where where
@ -663,7 +672,9 @@ impl Env {
#[inline] #[inline]
/// Get reference value from `Ref` without type check /// Get reference value from `Ref` without type check
///
/// Using this API if you are sure the type of `T` is matched with provided `Ref<()>`. /// Using this API if you are sure the type of `T` is matched with provided `Ref<()>`.
///
/// If type mismatched, calling `T::method` would return `Err`. /// If type mismatched, calling `T::method` would return `Err`.
pub fn get_reference_value_unchecked<T>(&self, reference: &Ref<()>) -> Result<T> pub fn get_reference_value_unchecked<T>(&self, reference: &Ref<()>) -> Result<T>
where where
@ -678,7 +689,9 @@ impl Env {
#[inline] #[inline]
/// If `size_hint` provided, `Env::adjust_external_memory` will be called under the hood. /// If `size_hint` provided, `Env::adjust_external_memory` will be called under the hood.
///
/// If no `size_hint` provided, global garbage collections will be triggered less times than expected. /// If no `size_hint` provided, global garbage collections will be triggered less times than expected.
///
/// If getting the exact `native_object` size is difficult, you can provide an approximate value, it's only effect to the GC. /// If getting the exact `native_object` size is difficult, you can provide an approximate value, it's only effect to the GC.
pub fn create_external<T: 'static>( pub fn create_external<T: 'static>(
&self, &self,
@ -739,6 +752,7 @@ impl Env {
} }
#[inline] #[inline]
/// Run [Task](./trait.Task.html) in libuv thread pool, return [AsyncWorkPromise](./struct.AsyncWorkPromise.html)
pub fn spawn<T: 'static + Task>(&self, task: T) -> Result<AsyncWorkPromise> { pub fn spawn<T: 'static + Task>(&self, task: T) -> Result<AsyncWorkPromise> {
async_work::run(self, task) async_work::run(self, task)
} }
@ -877,6 +891,11 @@ impl Env {
#[cfg(feature = "napi5")] #[cfg(feature = "napi5")]
#[inline] #[inline]
/// This API does not observe leap seconds; they are ignored, as ECMAScript aligns with POSIX time specification.
///
/// This API allocates a JavaScript Date object.
///
/// JavaScript Date objects are described in [Section 20.3](https://tc39.github.io/ecma262/#sec-date-objects) of the ECMAScript Language Specification.
pub fn create_date(&self, time: f64) -> Result<JsDate> { pub fn create_date(&self, time: f64) -> Result<JsDate> {
let mut js_value = ptr::null_mut(); let mut js_value = ptr::null_mut();
check_status!(unsafe { sys::napi_create_date(self.0, time, &mut js_value) })?; check_status!(unsafe { sys::napi_create_date(self.0, time, &mut js_value) })?;
@ -886,7 +905,9 @@ impl Env {
#[cfg(feature = "napi6")] #[cfg(feature = "napi6")]
#[inline] #[inline]
/// This API associates data with the currently running Agent. data can later be retrieved using `Env::get_instance_data()`. /// This API associates data with the currently running Agent. data can later be retrieved using `Env::get_instance_data()`.
///
/// Any existing data associated with the currently running Agent which was set by means of a previous call to `Env::set_instance_data()` will be overwritten. /// Any existing data associated with the currently running Agent which was set by means of a previous call to `Env::set_instance_data()` will be overwritten.
///
/// If a `finalize_cb` was provided by the previous call, it will not be called. /// If a `finalize_cb` was provided by the previous call, it will not be called.
pub fn set_instance_data<T, Hint, F>(&self, native: T, hint: Hint, finalize_cb: F) -> Result<()> pub fn set_instance_data<T, Hint, F>(&self, native: T, hint: Hint, finalize_cb: F) -> Result<()>
where where
@ -915,6 +936,7 @@ impl Env {
#[cfg(feature = "napi6")] #[cfg(feature = "napi6")]
#[inline] #[inline]
/// This API retrieves data that was previously associated with the currently running Agent via `Env::set_instance_data()`. /// This API retrieves data that was previously associated with the currently running Agent via `Env::set_instance_data()`.
///
/// If no data is set, the call will succeed and data will be set to NULL. /// If no data is set, the call will succeed and data will be set to NULL.
pub fn get_instance_data<T>(&self) -> Result<Option<&'static mut T>> pub fn get_instance_data<T>(&self) -> Result<Option<&'static mut T>>
where where
@ -946,18 +968,19 @@ impl Env {
} }
/// # Serialize `Rust Struct` into `JavaScript Value` /// # Serialize `Rust Struct` into `JavaScript Value`
///
/// ``` /// ```
/// #[derive(Serialize, Debug, Deserialize)] /// #[derive(Serialize, Debug, Deserialize)]
/// struct AnObject { /// struct AnObject {
/// a: u32, /// a: u32,
/// b: Vec<f64>, /// b: Vec<f64>,
/// c: String, /// c: String,
/// } /// }
/// ///
/// #[js_function] /// #[js_function]
/// fn serialize(ctx: CallContext) -> Result<JsUnknown> { /// fn serialize(ctx: CallContext) -> Result<JsUnknown> {
/// let value = AnyObject { a: 1, b: vec![0.1, 2.22], c: "hello" }; /// let value = AnyObject { a: 1, b: vec![0.1, 2.22], c: "hello" };
/// ctx.env.to_js_value(&value) /// ctx.env.to_js_value(&value)
/// } /// }
/// ``` /// ```
#[cfg(feature = "serde-json")] #[cfg(feature = "serde-json")]
@ -974,16 +997,16 @@ impl Env {
/// ``` /// ```
/// #[derive(Serialize, Debug, Deserialize)] /// #[derive(Serialize, Debug, Deserialize)]
/// struct AnObject { /// struct AnObject {
/// a: u32, /// a: u32,
/// b: Vec<f64>, /// b: Vec<f64>,
/// c: String, /// c: String,
/// } /// }
/// ///
/// #[js_function(1)] /// #[js_function(1)]
/// fn deserialize_from_js(ctx: CallContext) -> Result<JsUndefined> { /// fn deserialize_from_js(ctx: CallContext) -> Result<JsUndefined> {
/// let arg0 = ctx.get::<JsUnknown>(0)?; /// let arg0 = ctx.get::<JsUnknown>(0)?;
/// let de_serialized: AnObject = ctx.env.from_js_value(arg0)?; /// let de_serialized: AnObject = ctx.env.from_js_value(arg0)?;
/// ... /// ...
/// } /// }
/// ///
#[cfg(feature = "serde-json")] #[cfg(feature = "serde-json")]

3
napi/src/lib.rs
View file

@ -11,7 +11,7 @@
//! Because `NodeJS` N-API has versions. So there are feature flags to choose what version of `N-API` you want to build for. //! Because `NodeJS` N-API has versions. So there are feature flags to choose what version of `N-API` you want to build for.
//! For example, if you want build a library which can be used by `node@10.17.0`, you should choose the `napi5` or lower. //! For example, if you want build a library which can be used by `node@10.17.0`, you should choose the `napi5` or lower.
//! //!
//! The details of N-API versions and support matrix: [n_api_n_api_version_matrix](https://nodejs.org/api/n-api.html#n_api_n_api_version_matrix) //! The details of N-API versions and support matrix: [n_api_version_matrix](https://nodejs.org/api/n-api.html#n_api_n_api_version_matrix)
//! //!
//! ### tokio_rt //! ### tokio_rt
//! With `tokio_rt` feature, `napi-rs` provides a ***tokio runtime*** in an additional thread. //! With `tokio_rt` feature, `napi-rs` provides a ***tokio runtime*** in an additional thread.
@ -99,6 +99,7 @@ mod win_delay_load_hook;
pub use napi_sys as sys; pub use napi_sys as sys;
pub use async_work::AsyncWorkPromise;
pub use call_context::CallContext; pub use call_context::CallContext;
pub use env::*; pub use env::*;
pub use error::{Error, ExtendedErrorInfo, Result}; pub use error::{Error, ExtendedErrorInfo, Result};