README.md

threx

Spawn threads and run tasks on those threads from JS. Simple example that does nothing:

var Thread = require('threx');

var t = new Thread();
t.spawn();
t.join();

Install

Only works with Node.js v0.12.x or io.js. To install using Node do:

$ npm install threx

To install using io.js do:

$ iojs $(which npm) install threx --nodedir=<path_to_source>

To use in your project include this in your binding.gyp under "targets":

"include_dirs": [
  "node_modules/threx/include"
]

And then put #include <threx.h> at the top of your C++ file.

API

The API is still pretty scarce, but this is what we've got:

JS

Thread(): Constructor to create a new thread

Thread#spawn(): Spawn the thread. Only run this once.

Thread#join(): Join the thread and cleanup resources. Blocking call.

Thread#enqueue(obj[, data]): Pass a native method to be run on the spawned thread. This is meant to be used in conjunction with the native API. data can either be a v8::External or a Buffer. If a Buffer is passed then it cannot be a slice, and it will be zero'd out in order to hand control of the memory over to the spawned thread.

C++

Everything is namespaced under threx.

thread_resource_t: struct of the thread resource attached to the Thread() instance.

thread_work_cb: typedef of the type of callback that is called from the spawned thread.

export_work(v8::Isolate*, thread_work_cb): Pass it a callback of type thread_work_cb and it will return a Local<External> that you can return to JS and pass to Thread#enqueue().

enqueue_work(thread_resource_t*, thread_work_cb, void*[, size_t]): Pass it a thread_resource_t* and a thread_work_cb to have it queued to be run from the spawned thread.

enqueue_cb(thread_resource_t*, thread_work_cb, void*[, size_t]): Enqueue a callback to be run on the main thread, from the spawned thread.

get_thread_resource(Local<Object>): Pass in the object that was returned on Thread#spawn() and it will return the thread_resource_t*.

Examples

Here's a multi-threaded "hello world!"

// main.cc
#include <v8.h>
#include <node.h>
#include <threx.h>

using v8::FunctionCallbackInfo;
using v8::Handle;
using v8::Isolate;
using v8::Object;
using v8::Value;

using threx::thread_resource_t;
using threx::export_work;


static void test_cb(thread_resource_t* tr, void* data, size_t size) {
  fprintf(stderr, "hello world\n");
}


void RunMe(const FunctionCallbackInfo<Value>& args) {
  Isolate* isolate = args.GetIsolate();
  args.GetReturnValue().Set(export_work(isolate, test_cb));
}


void init(Handle<Object> exports) {
  NODE_SET_METHOD(exports, "runMe", RunMe);
}

NODE_MODULE(addon, init)

// run.js
var Thread = require('threx');
var runMe = require('./build/Release/addon').runMe;

var t = new Thread();
t.spawn();
t.enqueue(runMe());
t.join();

# binding.gyp
{
  "targets": [{
    "target_name": "addon",
    "sources": [ "main.cc" ],
    "include_dirs": [
      "node_modules/threx/include"
    ]
  }]
}