-
Notifications
You must be signed in to change notification settings - Fork 282
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Quest: N-API Support #444
Comments
I'm interested. |
@ciscojeremy Awesome! Are you on the community Slack? @kjvalencik is just now working on some refactoring so you might want to sync up with a chat. |
Nope, I'm not a the community slack. How do I join?
…On Thu, Oct 24, 2019, 7:53 PM Dave Herman ***@***.***> wrote:
@ciscojeremy <https://github.com/ciscojeremy> Awesome! Are you on the
community Slack? @kjvalencik <https://github.com/kjvalencik> is just now
working on some refactoring so you might want to sync up with a chat.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#444?email_source=notifications&email_token=AJBIX4KNNZBGQNQP7MGIVWDQQHVMBA5CNFSM4IZWOEP2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOECGCCLQ#issuecomment-546054446>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AJBIX4P2FBURIZPHWWAN5JLQQHVMBANCNFSM4IZWOEPQ>
.
|
The Rust Bindings community Slack is open to all; use the Slackin app to receive an invitation. |
Maybe this repo could save your time. https://github.com/Brooooooklyn/napi-rs |
👋 I'm working on |
This is the best dev-related news today! (came from Twitter) |
Wow. I’m so excited! I hope I can contribute something! joining the community slack |
I'd like to learn rust, but I have no experience yet, would like to contribute and have lots of experience with node tho. So if you think a total rust noob can be trusted with a certain task -- hit me :) |
@qwelias definitely! There will be some beginner friendly Rust tasks and likely some pure javascript as well. And, of course, testing and vetting of ideas are always needed! |
I'm looking at undefined/null for a start! Possibly bools too if they are as similar as I suspect, so all the global singleton values could be done in one go. |
What are some of the next possible steps here? |
i was planning on working on either objects or functions this Friday |
ah i thought numbers got in together with bools but i had them in a separate branch: #492 started working on objects and as i was writing a test case, i wanted to use tag checks like |
Nice! So it sounds like a first prototype-ish version would already be usable quite soon? |
I also started working on function calls (from JS into Rust for now) so parts of the existing test suite can be run on n-api. In-progress branch here: https://github.com/goto-bus-stop/neon/tree/functions @timsuchanek once both objects and function calls are in, some very limited use cases would be possible. I expect many real-world cases would want the Class stuff from Neon so you can pass Rust structs between JS and Rust, so they can live for longer than a single call. that would probably come next. |
Looking into getting the N-API runtime going on Windows today! |
We're almost there! I've struck out the items that are not needed for functional completeness and noted them in the new #596 issue for the deprecation plan. All that's left is to review the implementation of |
Would neon n-api support Electron without electron-rebuild or electron-build-env? |
@wspl Correct, they would not be needed. There would be a minimum n-api version that we might need to provide to neon with alternate means if we use APIs that aren't in the Electron node version yet, but we could probably do that with feature flags. |
… off one of the last remaining tasks for #444.
Prepare, once and future Neon contributors, for our noblest quest yet!
We are going to port Neon to Node's new N-API!
I'll explain. N-API brings to Neon the promise of a stable, backwards-compatible ABI—binary compatibility across all future versions of Node.
This is a big deal.
Portability across Node versions means Neon will finally be practical for publishing libraries, not just apps: a few prebuilt binaries should be sufficient for all downstream customers to use your native library without ever knowing the difference.
The stuff of legend, no?
Our Quest
Step 1. Create the feature flag
Step 2. Implement the port
neon::context::ModuleContext
type and pass it to the module initialization function inside theregister_module!
macro defined in/src/lib.rs
. The context struct will likely need to encapsulate the underlyingnapi_env
andnapi_value
as private fields. This can be implemented before we implement functions, with an unimplementedexport_function()
method for now.neon::types::JsFunction::new()
. The Rust callback can be stored as the extravoid*
data passed tonapi_create_function
.CallContext::len()
andCallContext::argument()
.this
: ImplementCallContext::this()
.CallContext::kind()
.ModuleContext::export_function()
shorthand method.neon::types::JsObject::new()
and theneon::object::Object
methods.neon::types::JsArray
.neon::types::binary
and the N-API functions for working with binary data, such asnapi_create_arraybuffer
,napi_create_buffer
, etc.neon::types::JsUndefined
andneon::types::JsNull
. @goto-bus-stopneon::types::JsBoolean
. @goto-bus-stopneon::types::JsNumber
.neon::types::JsString
. We'll need to explore what binary string representations can be used between the NAN vs N-API runtimes for constructing JS strings.Classes: This will require us to figure out how to do unique branding with N-API, but I believe<== not needed for functional completeness; see Transition guide for porting to N-API backend #596napi_define_class
supports this. (Here is one pure C example we can look to for inspiration.)neon::types::error
. We'll need to explore how N-API does throwing and catching errors. - @anshulrgoyal 🔒neon_runtime::convert::*
and thenapi_coerce_*
functions.neon::context
and the uses of various HandleScope internal types.neon_runtime::tag::*
.Task scheduling: See<== not needed for functional completeness; see Transition guide for porting to N-API backend #596neon::task
andneon::context::TaskContext
, and the N-API "simply asynchronous operations" API, which uses the same underlying libuv thread pool as Neon's current backend, but with N-API's stable ABI.Thread-safe callbacks: This can be implemented for N-API once we've merged an implementation for RFC 25, using<== not needed for functional completeness; see Transition guide for porting to N-API backend #596napi_make_callback
.node.lib
andwin_delay_load_hook
. Create a custom build script to link these on windows.We have just a couple remaining items to finish up:
JsBuffer::uninitialized
- see JsBuffer::uninitialized() for N-API backend #664Step 3. Deprecate the legacy runtime
Once we finish the complete port, we can switch the default feature flags to use the new runtime and publish a new 0.x minor version. Eventually after a few releases we can remove the old runtime completely.
How to Contribute
Building N-API-based projects
To experiment with the N-API runtime or do manual testing, you can create a Neon project that uses the right feature flags. To try it out, you can run:
where
path/to/neon
is the path on your local filesystem to a local clone of the Neon repo.Manual Steps
The output of
neon new
executed above will produce a project that fails to build. When using theneon
backend, eitherneon-build
should be used with a simplecargo build
orneon-cli
should be used andneon-build
should be removed. If both are used, the project will fail to build.There is an RFC (neon-bindings/rfcs#36) to replace
neon new
which will correctly generate a project. The simplest change is to editnative/Cargo.toml
:neon-build
dependencybuild = "build.rs"
native/build.rs
Note: If you create a Neon project nested inside the directory tree of a clone of the Neon repo, you'll need to add the line
to your Neon project's
native/Cargo.toml
manifest in order to build the project.Adding an N-API primitive
To add an N-API primitive, you should implement it in pure Rust (using
unsafe
as necessary, but only as necessary!) incrates/neon-runtime/napi
, and call out to the N-API backend exposed throughnodejs-sys
.When the Neon runtime needs to pass around a data structure, you can make two different definitions of the type, separated by testing the feature flag with
#[cfg(feature = "...")]
. You may sometimes need to refactor the types in the Neon runtime to accommodate differences between the legacy and N-API runtimes.Adding a test
The
test/napi
directory is the space for adding N-API acceptance tests. You can add native Rust logic totest/napi/native/src
and JS logic totest/napi/lib
. You can get examples of existing acceptance tests in our existing backend intest/dynamic
, which has the same structure.Will You Join Us?
As you can see, the quest ahead of us will be no small feat!
Indeed, but fear not: we're here to help you if you get stuck. And many of these tasks can be a great way to get started with contributing to Neon and even learning Rust.
Claim one of the tasks today by leaving a comment below or pinging @dherman or @kjvalencik on Slack!
The text was updated successfully, but these errors were encountered: