Konstantin Käfer

kkaefer

node.js extensions
with C++ and V8

C++ is faster than JavaScript. Is it?

If possible, write it in JavaScript.
JS ⟷ C++ boundary is slow to cross

function() { return Math.floor(133.7 / Math.PI); }

native JS	~83,333,333 calls/s
V8 return	~13,333,333 calls/s
V8 async	~1,745,200 calls/s
thread pool	~83,682 calls/s (0.1%)

Why C++?

V8 is written in C++
Wrapping existing C/C++ libraries
Use more threads

The bare minimum

modulename.cpp

#include <node/v8.h>
#include <node/node.h>

void RegisterModule(v8::Handle<v8::Object> target) {
    // Add properties to target
}

// Register the module with node.
NODE_MODULE(modulename, RegisterModule);

The bare minimum

wscript

#!/usr/bin/env python

def set_options(ctx):
  ctx.tool_options('compiler_cxx')

def configure(ctx):
  ctx.check_tool('compiler_cxx')
  ctx.check_tool('node_addon')

def build(ctx):
  t = ctx.new_task_gen('cxx', 'shlib', 'node_addon')

  t.source = ['modulename.cpp']

  # Must be same as first parameter in NODE_MODULE.
  t.target = 'modulename'

https://github.com/
kkaefer/node-cpp-modules

Compiling

$  node-waf configure 
Setting srcdir to               : /.../minimum
Setting blddir to               : /.../minimum/build
Checking for program g++ or c++ : /usr/bin/g++
Checking for program cpp        : /usr/bin/cpp
Checking for program ar         : /usr/bin/ar
Checking for program ranlib     : /usr/bin/ranlib
Checking for g++                : ok
Checking for node path          : not found
Checking for node prefix        : ok /usr/local
'configure' finished successfully (0.057s)
$  node-waf build 
Waf: Entering directory `/.../minimum/build'
[1/2] cxx: modulename.cpp -> build/Release/modulename_1.o
[2/2] cxx_link: build/Release/modulename_1.o ->
          build/Release/modulename.node
Waf: Leaving directory `/.../minimum/build'
'build' finished successfully (0.539s)
$

Requiring from JavaScript

$ node
>  require('./build/Release/modulename.node'); 
{}
>

Develop with
`$ CXX=clang node-waf configure`
Also test with GCC

Defining functions

modulename.cpp

using namespace v8;

Handle<Value> TheAnswer(const Arguments& args) {
    HandleScope scope;

    // Do stuff here.

    return scope.Close(Integer::New(42));
}

HandleScope cleans up handles created in this function
Preserve returned value with scope.Close()

Exporting functions

modulename.cpp

Handle<Value> TheAnswer(const Arguments& args) { ... }

void RegisterModule(Handle<Object> target) {
    NODE_SET_METHOD(target, "theAnswer", TheAnswer);
}

NODE_MODULE(modulename, RegisterModule);

target is what node.js calls exports

$ node
>  var mod = require('./build/Release/modulename.node'); 
{ theAnswer: [Function] }
>  mod.theAnswer(); 
42
>

Function arguments

modulename.cpp

Handle<Value> Fibonacci(const Arguments& args) {
    HandleScope scope;

    if (args.Length() < 1) {
        return ThrowException(Exception::TypeError(
            String::New("First argument must be a number")));
    }
    Local<Integer> integer = args[0]->ToInteger();
    int32_t seq = integer->Value();

    // ...
}

args contains elements of type Value
Cast to specific type with To* functions

Callback functions

modulename.cpp

Handle<Value> CallbackFunction(const Arguments& args) {
    HandleScope scope;

    if (!args[0]->IsFunction()) {
        return ThrowException(Exception::TypeError(String::New(
            "First argument must be a callback function")));
    }
    Local<Function> callback = Local<Function>::Cast(args[1]);

    // ...

    if (error) {
        Local<Value> err = Exception::Error(
            String::New("Something went wrong!"));
        Local<Value> argv[] = { err };
        callback->Call(Context::GetCurrent()->Global(), 1, argv);
    } else {
        Local<Value> argv[] = {
            Local<Value>::New(Null()),
            Local<Value>::New(Integer::New(42))
        };
        callback->Call(Context::GetCurrent()->Global(), 2, argv);
    }

    return Undefined();
}

Call automatically retains arguments
Don’t forget HandleScope scope at the top

The thread pool

JavaScript is single-threaded
I/O and CPU in thread pool
No V8 access from worker!

Passing data to the thread pool

struct Baton {
    uv_work_t request;
    Persistent<Function> callback;
    int error_code;
    std::string error_message;

    // Custom data
    int32_t result;
};

Not required, just a convention
Persistent is a Handle that stays around until diposed of

Calling asynchronously

Handle<Value> Async(const Arguments& args) {
    HandleScope scope;

    if (!args[0]->IsFunction()) {
        return ThrowException(Exception::TypeError(
            String::New("Callback function required")));
    }
    Local<Function> callback = Local<Function>::Cast(args[0]);

    Baton* baton = new Baton();
    baton->request.data = baton;
    baton->callback = Persistent<Function>::New(callback);

    uv_queue_work(uv_default_loop(), &baton->request,
        AsyncWork, AsyncAfter);

    return Undefined();
}

Worker function

void AsyncWork(uv_work_t* req) {
    // No HandleScope!

    Baton* baton = static_cast<Baton*>(req->data);

    // Do work in threadpool here.
    // Set baton->error_code/message on failures.
}

Function AsyncWork is blocking
Do not use any V8 code, not even variable reads
Convert values to POD or C++ types and store them in the baton

After function

void AsyncAfter(uv_work_t* req) {
    HandleScope scope;
    Baton* baton = static_cast<Baton*>(req->data);

    if (baton->error) {
        // Call baton->callback with error object.
    } else {
        // Call baton->callback with results.
    }

    baton->callback.Dispose();
    delete baton;
}

callback function is Permanent, need to delete manually

Wrap callbacks in TryCatch

if (baton->error) {
    Local<Value> err = Exception::Error(
        String::New(baton->error_message.c_str()));
    Local<Value> argv[] = { err };

    TryCatch try_catch;
    baton->callback->Call(
        Context::GetCurrent()->Global(), 1, argv);

    if (try_catch.HasCaught()) {
        node::FatalException(try_catch);
    }
} else {
    // ...
}

node::FatalException throws at the top of the event loop
Catchable with process.on('uncaughtException', ...)

API design

Challenge: Synchronous ➞ Asynchronous
Use EventEmitter
Chainable calls
Instantiating objects vs. functions
Make it hard to misuse
Make it feel as “JavaScripty” as possible

`node-sqlite3` API

var db = new sqlite3.Database('file.db');

db.run('CREATE TABLE baz (bar)');

db.get('SELECT foo from bar', function(err, result) {

});

No open() function, new implicitly opens
Statements are executed as soon as database is open
No need to “close” the database
No callback? 'error' event on the Database object

`node-blend` API

Blends two images of the same size

var blend = require('blend');

var image1 = <Buffer>;
var image2 = <Buffer>;

blend([ image1, image2 ], function(err, image) {
    // image is a Buffer of blended pixels.
});

No need to create objects with new if you don’t require state

Konstantin Käfer

node.js extensionswith C++ and V8

C++ is faster than JavaScript. Is it?

If possible, write it in JavaScript. JS ⟷ C++ boundary is slow to cross

Why C++?

The bare minimum

The bare minimum

https://github.com/kkaefer/node-cpp-modules

Compiling

Requiring from JavaScript

Develop with $ CXX=clang node-waf configure Also test with GCC

Defining functions

Exporting functions

Function arguments

Callback functions

The thread pool

Passing data to the thread pool

Calling asynchronously

Worker function

After function

Wrap callbacks in TryCatch

API design

node-sqlite3 API

node-blend API

More documentation

node.js extensions
with C++ and V8

If possible, write it in JavaScript.
JS ⟷ C++ boundary is slow to cross

https://github.com/
kkaefer/node-cpp-modules

Develop with
`$ CXX=clang node-waf configure`
Also test with GCC

`node-sqlite3` API

`node-blend` API