Node.js Node.js Interactive Europe 2016, 9 Mar 2017

Previous Meeting

Next Meeting

⏯

youtube image

►

From YouTube: Creating Native Addons - General Principles - Gabriel Schulhof, Intel Finland Oy

Description

Creating Native Addons - General Principles - Gabriel Schulhof, Intel Finland Oy

This talk is about creating node.js interfaces for native libraries written in C. It is not so much about the mechanics of writing the code, or about the structure of a npm package containing a native addon, but about the various situations you are likely to face when writing addons. It starts with the assumption that it is best to create an addon that provides as little abstraction as possible so as to allow you to provide a Javascript API to the consumers of your project that is itself written in Javascript. The portion of the node.js documentation that describes native addons, the V8 reference, and the reference provided by the Native Abstractions for Node project give you an ample toolset for creating native addons. Once you’ve managed to create your first native addon, and are ready to bring a complete native library into the node.js world, you will be faced with having to translate the artifacts of the C language into Javascript concepts. At that point, it pays to be systematic. It is beneficial to break the library’s API into constants, enums, structures, and functions, and bind each onto the node.js module you are creating in as automated a fashion as possible. In my presentation, I will describe some patterns for dealing with data structures, pointers, and callbacks one needs to pass to the native library. Finally, I will show some examples of projects where I’ve applied these concepts.

A

I'm going to talk to you today about writing native bindings for nodejs, so you know you have a see library or some other kind of library, and you want people to use it using nodejs so that they have an opportunity to write applications in JavaScript.

A

You know you want to appeal to the community that doesn't know how to use and how to write programs in C, then you're going to you're going to have to make a native ad on and when, whatever you're dealing with see, there are some common scenarios you're usually faced with, and those are the ones I'm going to talk about today.

A

So my assumption is that you know I I know how to write in C and I've used it for years, but in my recent past, I've been working with JavaScript, so going back to it, I wanted to use it as little as possible. You know just to accomplish the task and then put all my abstractions that I wish my my application developers to use write those in JavaScript.

A

So the benefit is that you know when, when your JavaScript interface is ready, it looks a lot like the capi, so you know you can even reuse the documentation. I use that all the time, but there are some things that you can avoid exposing to JavaScript that are specific to see. So if you have a function that that takes a function pointer in see, you know, then then in most API is it also takes a context.

A

Otherwise, the function pointer is pretty useless for generic purposes, and so the in JavaScript context is not a problem like javascript is the king of context. You can just make a closure call it a day right, so you don't need to expose that to see I mean. Why would you send a JavaScript object all the way in to see and then have it come all the way back when you can just put it in the context, then that's it.

A

The other thing that that you don't need to expose when you're writing our minimalist JavaScript API is things like like variable length or raise I mean see, doesn't have them right, so you always have two parameters. You have the array, which is just a chunk of data, and then you have an integer saying you know if you read more than this you're going to seg fault, but in JavaScript. Obviously the array length is always a member, the array, so you don't need to expose that either.

A

So in general, what you want to do is to avoid too many complications. Is you assume that the C library works as advertised right, so so data coming from there is reliable. So the only case where you have variations is, if you have a string that can be nulled and you know, then you should check. Is it a string and then, if it's not then set the JavaScript correspondent to null? But aside from that, you can pretty much trust all the data, because C strongly type right.

A

So if it's an integer, it's an integer for sure, on the other hand, from JavaScript, if you get any kind of data from JavaScript, it could be anything right. So so before you send it to see, you want to make sure that it is what you need it to be, and you you do that. First of all, with documentation I mean the capi says it takes an integer.

A

So if the application sends you a string well, you know you throw an exception and call it a day right and the other thing you want to do to keep to keep things simple. Is you want to avoid the the JavaScript thing where you know the function can take one parameter or you can take three parameters, and if the second parameter is is a function, then that's really the third parameter, because they left out the second parameter. All that stuff.

A

You just get that BBB very strict about it, because this is the lowest level of the API right. If people want to implement argument juggling, let them do that with with with your API and then give you predictable parameters and, of course require them to have a type. That's another kind of argument juggling.

A

So when you're implementing your your, your your ad on one one of the good practices that I found is to do to have to have the the C++ code mimic the way JavaScript works right and in particular, JavaScript can throw exceptions right, which completely blow the stack right and go to the nearest exception handler.

A

So so I found it very useful to to organize my c++ code the same way so that it works like JavaScript and except of course, I mean you can have exceptions in C++ as well, but I found that it's best to just to just have to have the function stack returned with like false or something and then and then you know that an exception has been thrown because the outermost binding doesn't return anything that's the way the the bindings are implemented in in node.

A

But, but if, though, if a helper that is called by the binding returns false, then you know that something went wrong somewhere deep in in your helper functions and you can just quit because you know that as soon as it goes back to JavaScript, an exception was thrown and it's going to jump so so this is. This is what I'm talking about right like at the bottom.

A

There you have, the you have the binding, which caused some helper function to establish the parameters that it needs to pass like doing, validation and filling out structures and so forth, and and and if anything goes wrong. It returns. False right and I throws an error and it returns false. If it calls a helper, then the helper throws the error. So so this is this mimics JavaScript, because the the exception is thrown at the point.

A

Where something failed, you don't return false and you expect the caller to interpret the return value as huh something went wrong, I, better, throw an exception, no throw the exception right there and then just bail, and you do this. You do this throughout the stack and then, if you do it that way, then then your functions can be composed. So if a structure contains another structure, although all the ones all the functions that you write that convert from JavaScript to to see, they will all behave the same way, so you can combine them.

A

So, for example, let's say we have a structure like these coordinates and- and we want to write a pair of functions that go from JavaScript to see and from C to JavaScript, so the c converter, let's write it so that it returns true. If the structure has been successfully converted to a C structure or throws an exception and returns false. If one of the parameters wasn't like a double, it was a string or something so so the other things.

A

These are see specific things that that that I found that I found good to do and that's to always pass in, obviously which see structure you want me to fill out and and obviously from which JavaScript object. You want to take the data right and the way I do it is you know if the validation succeeds? Partially then, then, I don't want to mess up the structure that was passed in by filling out some of the members, but then the last one fails, and so the structure is partially filled.

A

That's what I always do is I create a local variable that has the same type I fill out that one and if I successfully filled out that one I just basically assign it to the one that was passed in like right here at the bottom and then return true and call it a day. And of course, if you need to I mean you know it's not as simple as it sounds, because you know you can have you, you may need to allocate pointers.

A

If you have strings and so forth- and you know you, don't you don't get free clean up by doing it this way. So you still need to worry about that. But then you can just have like a go-to at the bottom. That says, if it fails, then just free and return false. You know, because you will already have thrown the exception by that, so so this this, for example, is how you convert to two coordinates.

A

First, first, you retrieve it up here you retrieve the latitude and then, if it's not a number, then you know you throw an exception. You return right away, otherwise you assign it to your local, see, structure right and you do the same thing for a longitude and altitude and if all is well, then you just basically copy it into whatever structure was passed in and that's it.

A

This is an internal function, so you don't really need to worry about what if the destination is no because this is not a function that is part of your API. This is an internal helper function, so you know you're responsible for not passing, though, and actually I'm currently doing things. This way my project, but you know, with with recent versions of non you, can you can?

A

Actually, you can actually add an additional check here which is like if you, if you create a string, then string creation may fail, and so so so so so this non new lat may actually be empty and and then and then that's a maybe type, and you can actually check if it is empty before you try to convert it to a JavaScript string. So these are just things which give you additional validation to avoid even more sec. False I haven't included those yet so so. The observation, of course, is because of the way or jeez.

A

Ok, so don't scroll on these slides moral of the story so yeah. So the observation to be made here is that if you, if you write your converters that way, then you can compose them. So you can reuse if you, if your C API uses the same structure in multiple places, you can use the same converter and and make it part of a larger converter and so forth. Now the JavaScript converter is somewhat simpler because we have chosen to trust data from the seaside.

A

All it does is return a JavaScript object and it accepts a pointer to a see structure and since, since there are two cases, one way, you're filling out an existing JavaScript object and one where you're creating one. It's cool to use one of these C++ specific things, which is that you can have a default value for for your formal parameter, which which creates a new object if it's not already there. So so then this is what the the jas converter for such a structure would look like very simple.

A

So so this is the default value that I'm talking about right, meaning that by the time you get to the body of the function, you always have a place, a JavaScript object into which to store your things, and then you simply simply store them and that's it and you return simple, as that and the same thing holds for the JavaScript objects. Right like you. Can you can compose those as well? You can assign an object that was converted from a see structure as a property of a larger JavaScript object.

A

So so these are the general principles. Now there are some things you can automate when, when you create this native ad on using our old friends is where did this go yeah there cat grab a knock right like, but this only works really for for, like preprocessor constants and any noms can't really automate functions because I'll show you why there are some API, specific semantics, which you cannot capture with script.

A

So so then the way I the way I always do my addons is is: is they end up with with these constants and then with the e noms namespace like this, so it makes for some longer JavaScript code, but whatever you know, that's what minify is for so then here's an example of a simple binding.

A

This is a very simple function. It takes primitively, valued parameters and it returns of primitively valued result, and these are macros which are basically you know. If the argument count is not to then throw an error and return, and if the argument County or if the arguments 0 is not a number, then return throw an error return. You know so so that you know bail, kind of approach and and then you just call the capi and then you set the return value right away, and that's it very simple.

A

So on the other hand, of course, when you're dealing with data things stop being so simple because now you're dealing with pointers right and so so what I found is that in a when you're wrapping, a library usually have two kinds of pointers. You have a pointer which, where where the pointer itself is not that important, but which is used for conveying data which exceeds the size of a primitive value right.

A

So it's just a structure and and you're interested in the contents of the structure, not where the structure is stored, that doesn't matter and and then there's the second kind of pointer, which is like a handle, which is very often found in in C libraries like a like a file star when you use, F, open or or you know, I mean UNIX ones are usually integers, so they fit into a primitive value.

A

But you know pretty much all libraries have these handles I, give a timer star or like if you take G lib you'll have plenty of handles, but the bottom line is with a handle. It's usually an opaque structure because the library is using it internally, but the value of the handle itself is very important and it's not like an integer. So so you cannot trust that it that it's an integer, in fact you shouldn't treat it as an integer.

A

So did I cover all the points here. Yes, so so then, so then, let's, let's, let's let's see how we do this with with a data structure using using this example with the with the coordinates right. So let's say we have. We have two api's. One of them defines a restaurant by name and one tell it tells you if there's a restaurant located at the coordinates given right. It's a very contrived example book. It's. It serves to illustrate the point. So so you have so here you have.

A

The local coordinates right which which the capi fills out right and then you use the converter. We've created to return it to javascript. Pretty simple, and in fact you you in this case you're filling out an existing value, so so this kind of brings the sea semantics to javascript. In that you pass in an empty object and you get a not on the object that has three properties so it, but whatever I mean it's a very low level, JavaScript API onto which you then build anyway. So it's it's all right.

A

So then, so then this is the other binding for for determining whether there's a restaurant at the given coordinates and- and in this case you convert to see, coordinates over here and you fill out the structure, and you can see that you can see the semantics. If the conversion doesn't work, then you bail, because the sea coordinates will have thrown an exception.

A

You don't need to throw the exception in the binding it's already thrown and then you set and then you call the api and you return whatever the API returns and that's it so so with handles with handles what libraries do is they usually give you like, like two bookends that one for creating the handle I want for telling the library thank you. You may now release the resource, so that's how it works with pointers. That's how it works with files sockets, you name it and and like handles, which are purely internal to the library.

A

They all have an open clothes. So there they behave just like JavaScript when you have set timeout and set interval, cleartimeout, clearinterval and so forth, and these are some of the examples. So so in that sense, all handles behave in a certain way right.

A

You have these, you have these book ends and if you overwrite the value, if you forget the the value of the handle, that's it it's going to leak right and if you try to release it multiple times, if you try to use it after you've released it, then then you know in it starts to go off the rails, so either nothing happens in which case you're, maybe lucky, except if you expect something to happen or an error is returned or you know so forth. But how do we bind this to JavaScript right?

A

Because, because, like I said handles it's it's not it's not a good idea to treat them as integers right, because if you pass an integer into javascript- and you know, people can overwrite it and then all of a sudden you've got these. These weird pointers pointing all over the place when they come back right.

A

So so so what I've chosen to do is I've chosen to use this Oh for crying out loud there is that it no there so I've chosen to use v8 and non because that's what note runs on currently to to create these? These special objects. I can javascript it's very easy to instantiate a new kind of object. You just create a function and then, when you instantiate the function it the resulting objects are of that type right.

A

So, but one of the v8 only features that is accessible only from C++ is to assign properties to these objects, which are completely invisible from JavaScript. You basically add pointers to to a class of object, and- and so so you can store these pointers in in a way that is completely invisible. It's not like it's not like defined property kind of invisible, where it's just not innumerable, but otherwise it's there, it's completely inaccessible from JavaScript. So so what I do is for four handles I've created this class, which which has three things it has instantiation.

A

You know you get a handle from the library and you turn it into something that you can use in JavaScript, which is completely opaque from JavaScript. Just like your handle is in your C++ side, and you have one where it converts back like give me back. My native handle so I can talk to the native library again and and then you have to have a third function which basically says.

A

Okay, this you know scrub the handle because I have released the native handle, but I don't have control of a JavaScript garbage collection, so so the JavaScript object may be around still, but henceforth it shall be an invalid handle. So so then so then, basically you you scrub the handle, and now it's a plain JavaScript object.

A

But the good news is since you've scrubbed the handle and since you know the type of the object, then, if somebody attempts to use it later on, you know that this is an invalid handle, so you're not going to blindly pass it through to the native API and potentially set for you can actually throw an exception. Saying hello, you've use it. You've used a stale handle order or whatever. So so. This is what the class looks like lots of code here.

A

Basically, you in- and she ate a new javascript class up here and then, when somebody says new, you create a new instance of that class and you set you set this you set. This handle the the native handle. You store it inside the instance and and you set aside room for a handle right here using this using a set internal field, count which, which nan wraps for you or is that v8 I I forget.

A

But anyway you can look at the API dogs and then you have the other function resolve which basically says give me back my native handle or if it's not there, it throws an exception. Saying sorry. This is a stale object and that's great because it informs programmers that they did something out of sequence right. So they you know they closed the file and then they try to write to it. That's that's just not right so so this is what it looks like in your bindings.

A

You create a new class and you give it this name so that you can distinguish one type of handle from another. It's very convenient and in debugger it's going to say remote resource handles I'm, just going to say, object right, so people will know what handle leaked or whatever they're trying to debug will. They will have more information? Oh right now, wow this really sucks all right. So in a binding. What you do is, is you just use the you just use the new and the resolve?

A

So so, in one case you you return a new handle and then you you resolve it when you get it back from JavaScript and and you know that it hasn't been messed around with JavaScript, because it's simply not accessible from there.

A

So there are situations where, where you can create the same, handle twice so if you're, just if you, if you just do like open and close, then you don't really have that opportunity, because whenever you call open you get a new native handle anyway, but there are api's.

A

Where, because of the limitations of see the the API designers have chosen to to give you back your native handle in a call back, so you can close it from the call back or whatever right, and so, if you, if you want to pass that on to JavaScript, it's tempting to just create a new JavaScript handle, because we have this convenient, call and call a new function now right. But that's a bad idea, because, because now you have to JavaScript objects which both contain this native handle right yeah.

A

So they both contain the same native handle and- and if you close, if you call clothes on one, then that native handle will become invalid. But now you have a perfectly valid native handle running around which doesn't have any I say you have a perfectly valid JavaScript handle running around which doesn't have a corresponding native handle because you've already closed the file. So you know if you call closed again, you will pass it through blindly to to the native side and you will be in trouble.

A

So, instead of doing, instead of just creating new native handles for new JavaScript handles for the same negative handle, what you should do is you should pass a reference to to the one native handle that you created into the callback and- and you do that with with a persistent object right.

A

So so you create a persistent object in your binding and then you pass it to the callback and then in the callback you give it back to JavaScript as a convenience right and and then you will only have one native handle running around so it's over here where I commented out native handle new right.

A

This jas remote handle new instead of that, just just dereference your persistent and give that back to JavaScript, and you will maintain the one-to-one relationship with native handles so callbacks callbacks are the major thing that that you will run into because you know you have to create function, pointers and so forth, and- and there is one very, very important thing that I ran into with with trying to trying to bind a fledgling library, which is that the kind of ours of the fledgling library forgot to include the context parameter into in one of their in one of their callbacks right.

A

So, like you know, JavaScript, you know you can make functions on the fly. All the time like. If you declare a function inside another function, whenever you call that function, instantiates a new function, object right, but in see you can't do that right and see when you declare a function. That is physical. That is a chunk of memory from A to B, which is marked, read only and executable and and it's stored. Who knows where and that's it you can't just copy it right and making it make a new instance of it right.

A

So so, if you don't have this context parameter you are are in pretty deep water right. In fact, you you need to. You need to use crazy stuff like like foreign function, interface, where, where you essentially can create new functions at runtime by using some really crazy assembly, which is of which the it is documented, 459 platforms, and you hope that it works right. So, just if there's no context, then just you know file a bug with with the native library, so I'm not going to not even going to go there I did it once.

A

Okay, it's ugly, don't do it, but you know it's much easier to just file a bug upstream to please add a context to the callback because nobody's going to use it that way, anyway, all right, so there are two kinds of callbacks that I've been able to identify, one which is like the typical completion call back. If it gets called, it means it would never get called again and then there's the other kind of callback which is like you open the file. Here's your handle. You can have callbacks on the file.

A

When the read completes, when the right completes, you can even have periodic callbacks. You know file modification callback. You know someone outside process modifies the file, you you get notified and you keep getting notified about stuff that happens to this handle until you say, close the handle. So so this is the book ended version which, which is this explicitly removed and the other one is the implicitly removed.

A

So the distinction is important for us, because whenever we get a handle, we're going to attach stuff to it, so we need to know when the handle will go away and and and the when the handle will go away is highly API specific. So you know automation at that point is out of the question because you need to think about when it's going to go away. So at that point it's like AI complete right when it goes away. So because n, you need to remove stuff when the handle gets closed, so so yeah.

A

So and then, of course you have the hybrid case where, where you can, you know close the file release the watch, but if the callback returns false, it does the same thing right and so here there's there's, there's a really interesting gotcha! Alright, because you know, let's say let's say the file. The application goes like this. If the file changes read the file and if the file contains ABC, then I don't care about changes anymore right. So so you open the file or you start watch the file and you watch for the changes.

A

The change arrives and you say close the handle, but you say so from the change notification call back right and then, additionally, you return false, saying: I, don't want to watch the file anymore. So it's like you, return false meaning, free the handle and free all the binding associated stuff that you have stored on the handle, but your you've also freed it explicitly right.

A

So if you, if you're, not careful, then you're going to free it twice in your bindings, you you're going to free the overhead associated with the handle twice, and you know you're going to have yourself a really nice segfault again so, but the good news is that our native handle right, we scrub it and then we can check. Did we scrub the handle? Already? Yes, okay? Well, then, I don't need to scrub it again right, but we need to implement that and you need to remember that.

A

So that's why I'm talking about it is please avoid this pitfall. Hello pitfall ahead. You know so so here's an implicit call back going back to the simple case, so you know you call you call your JS call back whenever you get a native call back. You retrieve the jas call back from the context which you do have, fortunately, because we're talking about the mature or API, not one of those fledgling ones, and then, after that, you can be confident that this callback will never be called again.

A

So you can free all the associated stuff with it doing all these deletes over here. So now, with explicit one, like I said, you have the book ends and you don't free it. You free it's only only when only when you, when somebody calls you know close the file or stop watching, but but the difference.

A

Another difference between implicit and explicit is that for an implicit call back, it's enough to pass just the JavaScript function that you're supposed to call and any convenience handles to the native call back, because that's enough information to call the callback right, but with a with an explicitly removed, call back you need you need to also. You need to also pass all this all this information that you would normally pass through the callback.

A

You also need to pass it to the handle, because when when, when somebody says stop watching the file, you have to ask yourself: okay, so which callback? Do you want me to remove? You know like which JavaScript callback, it's not just enough to know which native handle I'm supposed to pass on to the native API, which persistent objects were there I?

A

You also need to know the callback that you're supposed to remove, so so at that point, what you do is when you, when you wrap your when you wrap your native handle, you don't assign a native handle into this into this JavaScript rapper, but rather you assign a structure into it which contains the native handle, and it contains everything that you need to clean it to clean up, because that's everything that you're going to get back when somebody says close, the handle I've had enough watching this file, and so so it is at that point that you need to have everything that you need to free, not inside the callback.

A

So so, then you create this. This kind of self-referential structure and it is self referential, because it's a see, structure and it contains the this convenience handle which are going to use in the callback. It contains the function that you got from JavaScript or persistence, reference to that function, and it contains the native handle, of course right. But this this this handle right is actually the the JavaScript handle that you created that contains a pointer to this structure.

A

So that's why it's self referential right so so so this j/s handle actually contains a pointer to to do this structure, so it references itself, but you it's good because you need it from both the callback and from the binding. So so this is what I'm talking about.

A

So when, when you create this, when, when somebody says I want to watch this file, then you create one of these data structures which I showed you and of course you store the watch in one of its members and you store the function which which the the application has asked you to call. And then you also store this thing itself inside inside this see structure and then, of course, you sent back the the wrapped handle to JavaScript, and now you know what you know which call back to remove.

A

You know which native handle they're talking about, and you know which javascript object wraps that negative handle when the callback does arrive. So then, so then, when you unwatched, you have everything you need to clean up and as if nothing has happened, just like the native API cleans up as if nothing has happened.

A

So you have, and you use resolve, to get back to pointer to your native structure and then and then, of course, if the, if the on watch works, then you delete everything and everybody's happy and you have cleaned up and notice that this is what I'm talking about this is. This is what completely prevents automation like you have to actually check the return value of the native API, and at that point it's completely API dependent like it could be a true/false. It could be a value of an anom.

A

You know it could be negative one if it's like a sis call meaning there's an error, so keep all this stuff that you allocated in the watch or keep it around, because the watcher hasn't been removed and failed to remove the watcher. So you need to process these values, making this up on the exercise available only to humans to actually implement this. So now. This is what the callback looks like again.

A

It's almost the same as a as an implicit call back except you don't delete anything because this callback could be called any number of times. So you need to keep this context around, so you at the end there you can see the the JavaScript call. So when you have a hybrid car back then then, then things get interesting and this is how you avoid the double free and- and we do it by by calling resolve alright. So so so. This is what we have here right. It's almost the same again as the explicit one.

A

So here we call right and except we have a return value, and then we convert the return value to a boolean, which we then pass along to to the native library right and if the return value is false, then then we do not assume that that the pointer that we got here is still valid because as part of the call, this call may execute any any number of JavaScript frames embedded in one another, one of which could be a call to on watch file name in which case this this this object here.

A

This object will have been scrubbed by our previous API by the implementation of our API. So then, so then, after the call this this pointer may no longer be valid, which means you have to resolve it again.

A

So so you resolve it again and you throw an exception and, and the program is going to say: oh okay, well yeah, okay, so I've double freed it so like. Okay, maybe I don't need to return false there anymore or maybe I shouldn't free it explicitly. If I'm going to free, they implicitly or you can just ignore it. It's up to you. You know it's! It's really up to you, you're implementing the binding, but the bottom line is you will not set fall if you, if you resolve it again afterwards so anyway, that's that's it.

A

Thank you very much and I would like to thank my colleague bubble, who helped me with these things. He ran into them. I ran into them, and so we hammered these out and I figured okay, okay, okay cookie. We should write these down because you know other people may run into these. So let's just prevent that situation, nip it in the bud so to speak. So, in conclusion, the motto is: oh, what fun it is to write the jas interface hey, but anyway, that's just my conclusion.

A

So if you, if you guys, want a far more verbose treatment of all this, please go to this address and read it. If you can bear with me file issues, file, PRS and that's it. So if I have time for questions, then please otherwise just knock me off the stage or something do I have time for questions.

A

What time is it no I? Don't? Okay, bye-bye.