OpenJS Foundation OpenJS World 2021, 2 Jun 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Building Modern Native Add-ons for Node.js in 2021 - Kevin Eady, Hive Streaming & Gabriel Schulhof

Description

Building Modern Native Add-ons for Node.js in 2021 - Kevin Eady, Hive Streaming & Gabriel Schulhof

Quickly get up to speed developing modern Node.js native addons. This fast-paced talk, presented by members of the Node-API team for all native add-on developers, covers recent enhancements to Node-API. Support for multi-threaded and asynchronous programming in Node-API has been significantly improved. New abstractions such as thread-safe functions and the Addon class greatly simplify the effort needed to implement asynchronous add-ons. New helper methods support date objects, BigInts, retrieving object property names, and detaching ArrayBuffers. Tools used to build and deploy native add-ons also continue to improve. Developers can build with CMake.js in addition to node-gyp. Prebuilding binaries significantly improves the experience of native add-on users. Deployment options permit serving these binaries from GitHub releases or bundling the binaries in the npm module itself.

Join the speaker for live Q&A on Slack: Thursday, June 3 from 12:00 - 12:20 PDT / 21:00 - 21:20 CEST, channel - #openjs_world-development

A

Hello, everybody welcome to opengds world 2021 and our uh presentation about uh node.js uh node api, um we're gonna be talking mostly about how to build modern native add-ons. uh Node.Js is uh node. Api has been around for a while and uh it has enabled everybody to build uh api stable add-ons, but we've we've had uh significant features added recently and those are the ones we would like to talk about.

A

And my name is gabriel: I'm a member of the node.js tsc and of the node.js node api working group, and I originally contributed some portions of node api, like promises, exception, handling, environment, propagation mode, module, loading, wrapping, unwrapping of objects, threat, safe functions and context-aware add-ons.

B

And I am kevin eady, I'm a api team member, primarily working on the node add-on api wrapper, we'll talk about that shortly and I'm focusing mainly on threadsafe functions and asynchronous programming in general building native apps.

B

So when you need to compile your c plus code to run on node, we there exists multiple ways to compile your code. Currently, one method to use this is node gipp. This is the de facto method that exists whenever you install node this application. This build system is installed on your machine as well.

B

This allows any dependencies that you install. They don't necessarily have to also install this in order to compile their add-ons.

B

Another alternative is cmake.js. If you have used c plus build systems in the past, you may be familiar with cmake. This one allows you to easily integrate with other c plus plus projects that are also c make based.

B

This will easily allow you to incorporate the dependency trees that you need.

B

However, all of those require compiling the code. Every time you install the package, there are additional methods that allow you to download pre-compiled, binaries and use those so that you do not have to compile every time the package is installed.

B

One method is node pre-gipp, this one integrates easily with github releases and another one is pre-build. This one integrates easily with amazon s3.

B

So these two solutions, when you compile your code as a developer as the package maintainer, you can upload the built binaries to a repository either github or s3 and depending on which solution you use, it will download those directly instead of having to compile.

B

Node apis can only be called from the node thread. There exists multiple apis in order to facilitate the communication between your application and the native node thread.

B

There exists multiple different ways to perform asynchronous programming with node we have the async worker, which will be able to create a single worker thread which will execute your logic on this worker thread and when your logic is completed, you can call back to the node thread with the result on this callback you're able to transform your native c plus data into the node data, as well as the async worker. We have some node add-on api, specific extensions, the async progress worker and the async progress queue worker.

B

What these allow you to do is ping from your your native thread to the node thread, various progress updates, then. Finally, we have thread safe functions. These are full featured apis that allow you to create as many threads as you want and ping into the node api, as you find necessary.

A

uh One one one small addition is that one of the crucial differences between the the async workers, progress or otherwise in the threats they function is that in the case of the async workers, the the threading implementation is not up to you so in in the case of async workers, you're relying on node.js to create the threads, whereas in the case of the threadsafe function, node.js creates only the communication mechanism and it is up to you to use your own threading implementation or to create a new threading implementation back to you. Kevin.

B

All right and the first example we'll talk about is async workers.

B

So async worker is implemented in both the node api, which is the c based abi stable that we have as well as node add-on api, which is the c plus plus wrapper the async worker, as gabriel mentioned.

B

This would end up creating the worker thread internally, which internally may be a lib uv worker thread, but you as the programmer have no control over what that worker threat is. It is a thread created by the underlying system.

B

When you create this async worker, you provide two callbacks the execute and the complete callback. The execute callback is what you use to run your native c, plus plus logic outside of the node thread.

B

When that finishes, you call the complete callback with your re, with your c plus result and there you can transform your native c plus data into the node data.

B

In addition to a normal async worker, like I mentioned, we have the progress worker. This has an additional callback which is the on progress. Callback, the on progress, callback executes also on the node thread, which allows you to ping into from your c splits thread into the node thread and the final variant that we have is a progress day. Sync progress, q worker this guarantees, a progress update every time that you would like to send a progress update um next, we'll talk about thread, safe functions.

B

These are feature-rich apis that give you full control of how you would like to use node in any of your multi-threaded applications.

B

Thread, save functions are backed by a message queue and when you in your native c plus code, want to communicate with the node thread, it's basically a request that you, post on this message, queue to say. I would like to execute some code. The way that you place a request on this message.

B

Queue there's two different ways: there's a blocking call which will wait for the queue to have space for you to put in your request, and then we also have a non-blocking call which, if your queue is full, you would end up receiving a special status saying the queue is full with thread safe functions at construction. You specify some few data.

B

What you have first is your initial thread count. You also specify your maximum queue size. This goes back to how we were talking about the blocking calls and non-blocking calls. If you specify an unlimited queue size, then you would never be it would never block, because you would always have space to put something in the queue right.

B

But if you have say a cue size of 100 and the queue is full and you try to make a post at that point, if you make a blocking call, it will block and wait until there's space and the non-blocking will just say it's full and you have a couple of callbacks.

B

We have a javascript function, callback, a call, js callback and the finalizer callback. The initial thread count is like I said you provide at the beginning and it's stored internally.

B

Once this counter reaches a zero, the thread say: function is no longer available for use and will be cleaned up and finalized.

A

And as kevin pointed out, uh having things that defined statically at the global scope is no longer such a good idea, because nowadays you can have uh threads running not only on the native side, but you can also run javascript in multiple threads now. This is not the same as native threads, because what you're, basically doing on the javascript side is creating a whole node.js world.

A

Every time you, you start a new node.js thread and what that basically means is that if you require a native add-on from one thread and then you require it from another thread, that's going to be two copies of the native add-on right.

A

But uh but you know having variables at the global scope, thus is not threat safe because um you don't necessarily load multiple copies of the memory area where these global variables are are stored, because, usually, when you look since, since native add-ons are stored as shared libraries, a shared library is not loaded multiple times from disk, it's only loaded once and so so what you consider to be a global static variable exists only once in the in in actual memory, and so, if you start accessing the same global static variables from multiple threads, then you end up.

A

Shooting yourself in the foot. That's sooner or later, sec, faulting and yes, c, plus plus nowadays has something called thread: local as a as a storage class specifier. However, that is also not recommended, because uh a javascript thread may or may not coincide with with a native thread, so it is possible to create a javascript world without creating a new thread in which case into that javascript world.

A

A native add-on will be loaded, but really it's two worlds running uh in sequence, back and forth time, sliced and cooperatively multitasking on the same thread, and so the best solution is to use self-contained add-ons where it is guaranteed that multiple instances can be launched and uh the the cleanup is no longer process cleanup. It's cleanup of this javascript world, which may be the process, it may be a thread or it may be multiple javascript worlds.

A

We call them environments running on the same thread since you don't know which it is it's best to to use these apis to store what you need in terms of uh global data and accordingly, we made an api and a per add-on instance variable. It is no longer shared among add-ons, and so this gives us a good hook for for adding native data. May I have the next slide. Please.

A

So we have several tools that support this. On the c side, we have an api module in it, which, which is basically a macro uh that plays the role of uh a function header with, and it gives you the formal parameters, env and exports, uh where env is an api environment and exports is an api value. So it's it's a very usual arrangement.

A

So basically uh it is when you call an api module in it. It is expected that it's followed by a body that is the implementation of a function which can assume that variables, e and v exists, uh env and exports exist and that env is of type an api and exports is of type and api value.

A

And so here you do the usual initialization, uh except that now you you can be certain that this add-on can be loaded multiple times and from multiple threads and so forth, whereas with with um what did we have before um an api, if you just use an api module without using an api module in it, then that may or may not be nowadays an api module works as well, but there was a period when it didn't, and so so we introduced this macro which ensures that it will always work may have the next slide. Please.

A

So where do you put your data? Just because your module is is, is now supports getting loaded multiple times, you still need a place other than global static, to put your data right and so to to support that. We introduced methods. Napi get an api set instance data and it's they're very simple methods.

A

They basically associate one void star pointer with uh an instance of napi n and set obviously sets it get obviously gets it. If you set it twice, then then it forgets the old one. So be very careful. It's basically a matter of of uh uh project management to decide who gets the privilege of of of calling this and and setting the the data for everybody, and it is their responsibility to then sort of uh delegate access to this so that others may attach pointers.

A

If you, if your project structure happens to be such otherwise, it is under your sole discretion. What you do with these two apis.

A

It accepts a clean up parameter. So the usual napi finalize uh mechanism works with this data as well, so that you can it basically acts as a destructor uh when you're, when your add-on is being uh cleaned up, and so that way that way, you can align the life cycle of your data with the life cycle of your add-on.

A

Next slide, please so here's an example right: we define a structure, called add-on data right and we define a deleter for it, a finalizer, and so so we use an api module in it, because this guarantees that our module will be uh available multiple times and it will be loadable and will work correctly when loaded multiple times and inside the body. We create an object of type of type add-on data and we call net an api set instance data and we pass it the this data and the and the deleter right the finalizer.

A

And if you look on line 5 through 10, that's when uh our function gets called from javascript and we can maintain so we can access this global data by using an api, get instance data, and then you can, you know basically use it in whatever stateful way. You would use a global variable that you would have had in in previous versions of of of your add-on implementation.

A

So yeah, I I guess, that's that's the most basic usage of of set and get instance, data next slide, please so in in uh node add-on api. We we have the luxury of of of uh uh having more convenient, c, plus plus uh abstractions. On top of this, and one of the one of the most uh intuitive ways that you can, you can create uh and make use of, uh uh create self-contained add-ons and make use of add-on and api set and get instance. Data is by using the add-on class.

A

The add-on class works almost exactly the same way as object, wrap, meaning that you, you you take a c plus plus class and you basically expose it to javascript only in this case, um the life cycle of an instance of this class coincides with the life cycle of an add-on instance. So, basically, methods that you add using the instance method.

A

Api to this add-on class are basically your your bindings. They are not. They are not associated with with a class that you might expose, but they are associated with the add-on itself and uh in the next slide, which I'm now kindly asking for. You will see how how this all hangs together.

A

So so this is the this is the definition. This is a complete and functioning uh node add-on, api add-on, the class my add-on is a subclass of an api add-on and it in the in the constructor.

A

You basically define all the methods that you would like your add-on to have, and you use that using define add-on and in this, in this case we define a very simple add-on which just increments a value, and um it and basically uh doesn't do anything else, and so we expose that method as the increment method to javascript and when the method gets called it increments.

A

A value called x and you notice notice that uh the increment method on line 8 through 10 is basically the c plus version of the method in the previous example, that is, that has the an api get instance, data call built in so by so so.

A

The increment method is an instance method of class miad on it's, not a static method right, and so the instance that it receives was stored uh in on the environment using napi set instance data, and so even though, even though increment is not, uh is not a a javascript uh object. Instance method. It is a c plus plus instance method, and so you can easily access this state and you don't have to store any global variables. So, in older versions of this api into x equals zero would have been declared at the global scope.

A

But now you don't have to do that, and the the construction and destruction of these uh instances is handled by an api or no data on api itself, and you declare that you wish your add-on to be represented by class. My add-on by using this new macro called node api add-on.

A

We have node api module, which just which creates an old-fashioned module where you have to use uh the instance data yourself, um but this this uh this macro uh additionally gives you the uh the convenience of not having to do that anymore and and and uh the methods of of the my add-on class will will uh retrieve the instance data from the environment for you, and so you can just treat everything as an instance variable next slide. Please.

A

So um what else? What else do we have? Besides, besides multi-threading and and context-sensitive add-ons, which can be loaded multiple times? We also, we also added several like convenience methods, because they proved very popular.

A

One of them is date object. Obviously it's it's used extensively in javascript and very often it gets transferred to the native side. We added big end support as as it rolled around in the in in the engine. We also rolled it out into our api.

A

We added support for detaching array buffers, which means basically you you promise that you will no longer use the array buffer and it just turns into sort of a stub object, and it cannot be used anymore next slide. Please, and we also added an api to freeze and seal javascript objects. This is very useful for for electron.

A

It basically renders a javascript object, variously unable to be extended and so forth, and the properties are all frozen, so they cannot be changed anymore and we also added uh an api to tag a javascript object for type checking. Now what this means is that, um once once an object is tagged, uh you you can later check what what the value of the tag is, and you can be certain that that the the native data that you associated with that object is indeed a pointer of the correct type.

A

So the story behind this is that we realized that using prototype manipulation, it is possible to fool a native add-on into thinking that an instance of a of a certain class of of javascript object is of that class while while in reality being an instance of a different class, and so so. What this means is if both of these javascript classes were created using object, wrap, meaning that their methods are backed by native methods.

A

Then it is possible to to retrieve a pointer that refers to a native structure of a different type and cast it to the wrong type of structure using prototype manipulation. And this is especially true if you have multiple native add-ons interacting with one another and objects from one native add-on, end up being passed into the other and so forth. And so to avoid that, we are now making it possible to unambiguously tag an object using uh like a uuid and which is basically stored as two two consecutive 64-bit integers.

A

And so you can. You can basically paint the object with the uuid and then later on, retrieve the uuid and compare it with one that is stored in your add-on. And, yes, you can store this in a global static way, because it's read-only, you store it once it's const, and so you can read it from any number of threads. You cannot write to it, so this so the so the context sensitivity is not affected by uh by by this uh uh by these tags, so these tags are unaffected by context.

A

Sensitivity next slide, please all right. So this is all these are all the modern tools that are available to you. So you know: where do you get started? So one of one of the best ways to get started really is is to just pick something that you want to do like. What do you wish node.js had that you had when you were still doing c, plus what kind of cool library that does image processing encryption uh some network protocol?

A

You pick one of those libraries and you start writing bindings for it right and you can use all the tools that we discussed and you can look at these resources to see all the basics for for writing uh add-ons. So, for example, the node api documentation is a great place to start it's a c api.

A

So if that's not to your liking, then you can jump straight to the c plus plus wrapper, uh which will result in code that essentially ends up calling the c api in in certain well-known and and and uh often use patterns. So you can think of the c plus wrapper as basically a really really really fancy set of like macros.

A

um So you do not sacrifice api stability. If you use the c plus press wrapper, that's probably the most important take away. We have a great many uh tutorials. uh We have examples of of simple add-ons and simple calling patterns and how you get from javascript to native and back to javascript synchronously asynchronously using safe functions. All those examples are are at the link you can see. We have.

A

We have a workshop that that you can watch uh and we even have a conversion tool which uses regular expression to take regular expressions to to take your existing uh project if you've already ported something to to node and you've already written bindings for it.

A

However, you wrote them in nan or or directly in v8, then we'll try to do a decent job of catching all the places where we can do like a one-to-one mapping expect many compilation errors afterwards, because, obviously it's not a perfect tool, but it should give you a a good start um on uh on getting getting to an api and to abi stability. As a result, all right, then we have, we have a generator which basically creates a skeleton module for you, which you can then flesh out and add bindings to.

A

And we have two different versions of this uh gen epi is is, is, is another, is another option you might have and we have, if you, if you're, not a big fan of cnc plus plus we have bindings for neon, I mean for rust via via neon, and we also have an api rs. So you can write your add-on in rust.

A

Essentially, and then you can, you can use the an api implementation provided by node.js via the rust language rather than directly using c or c plus plus and finally, uh the the things kevin talked about uh at the beginning about uh packaging. Your ad on once you have it. um Pre-Build is a is a great solution, um and- and one thing that I might add to all of these uh solutions- is that uh they all fall back to compiling the code.

A

If you happen not to have provided uh a precompiled binary for that specific platform or that specific architecture, so they all try to compile the code if they fail to download a pre-built binary. So so it'll it'll solve a lot of your problems and if it doesn't- and you get a you know, you may get fewer bug reports because people actually figured out that if they have a compiler, it'll still work. So it's it's a good fallback to have next slide. Please.

A

Yeah, so so these are, these are links to to the other tools that kevin was talking about.

A

Pre-Build defy is another tool that allows you to pre-package and uh and build add-ons uh no pre-jip, likewise different slightly different flavors uh c-mac js is not such a package. However, it is a way to avoid using nodejib um and uh it it integrates better. In fact, no jip is is sort of kind of uh unmaintained now so we're using it for node and we're maintaining it only in so far as node.js needs it, and so it's it's.

A

Actually, it's actually a good idea to migrate to to a more widely used, uh build system if you can, and so uh we have an example like a real life example from mongodb uh about uh how how one specific add-on was migrated from from nan to to node api, um and so you can read up on on the ins and outs, gotchas and so forth, of of of people who have gathered real life experience in in this area. That may also help you, with with your own porting next slide. Please.

A

And finally, if you would like to contribute to to our effort you can you can uh read about uh our work at abi, stable, node? uh That's where we keep sort of the the design discussions and and the milestones that we wish to achieve.

A

And, uh of course, if you find issues uh and you would wish to contribute to an api or any other part of node, you can just open the repo and and uh file an issue file. A pr, and if you wish to contribute to the wrappers, then know that on api is the place to go. That's where we maintain pull requests and issues that that people find, while using our our node api, wrappers, the the c plus wrappers and, of course, you're always welcome to to join our meeting.

A

uh It's uh weekly on fridays at 8 a.m, pacific time and we always we're always happy to see new faces so by all means, if you wish, if you're interested in getting up to speed with contributing or if you just found the typo and you feel like you need to share it with the with the group by all means, uh come on to the meeting and we'll be happy to receive you. That was it folks.

A

Thank you for listening. Thank you. Bye.