A native module for Node.js that provides an asynchronous, evented and/or continuation passing style API for moving blocking/longish CPU-bound tasks out of Node's event loop to JavaScript threads that run in parallel in the background and that use all the available CPU cores automatically; all from within a single Node process.
TAGG2 is thread_a_gogo module's fork,it require nodejs version>=0.8.x, thanks for Jorge Chamorro Bieling.
TAGG2 support windows, linux, mac.
With npm:
Threads A GoGo2 module is supported windows, linux, mac.
Make sure, node-gyp has installed.
npm install tagg2
From source:
git clone https://github.com/DoubleSpout/node-threads-a-gogo2.git
cd node-threads-a-gogo2
node-gyp rebuild
To include the module in your project:
var tagg2 = require('tagg2');
var tagg2 = require('tagg2'); //require the module
var th_func = function(){
console.log('i am in thread,my file path is :' + __dirname);
//in thread you can do some cpu hard work,such as fibo.
thread.end("thread over");
//when thread over, the string "thread over" will transfer to main nodejs thread.
}
var thread = tagg2.create(th_func, function(err, res){
//var thread = tagg2.create(th_func, {buffer:buf}, callback); may transfer buffer to thread.
if(err) throw(err);//thread occur some errors
console.log(res);//this will be print "thread over"
thread.destroy();//make suer to destory the thread which you have created
});
tagg2 module support thread pool and process pool, that's will be created first,and do any other number of hard works.
when you have too many threads, your program may be out of memory,so pool will protect you from that.
var tagg2 = require('tagg2'); //require the module
var buf = new Buffer('tagg2 buffer'); //create the buffer to transfer to thread
var th_func = function(){
console.log(thread.buffer.toString());
//this will print 'tagg2 buffer'.
thread.end("thread over");
//when thread over, the string "thread over" will transfer to main nodejs thread.
}
var thread = tagg2.create({poolsize:10,dirname:__dirname});//create a pool which size of 10.
thread.pool(th_func, buf, function(err, res){
//thread.pool(th_func,callback); may not transfer buffer to thread.
if(err) throw(err);//thread occur some errors
console.log(res);//this will be print "thread over"
thread.destroy();//destory the whole thread pool
});
##API
##tagg2
object, you can get tagg2 object from require('tagg2');
##tagg2-thread and child process
tagg2 thread using pthread to create a worker thread or create a thread pool.To set options.fastthread=false, switch to child process model,you can using any nodejs api in it,make sure when the thread or child-process work finished, call the function thread.end([buf]),then the callback will be called,and the thread will return into the pool if you set a thread pool.
###tagg2.create(...)
return a thread object, the thread object has some methods and properties follow. see below.
ex1. tagg2.create(thread_function)
ex2. tagg2.create(thread_function, callback)
ex3. tagg2.create(thread_function, options, callback)
ex4. tagg2.create(options) //to create a thread pool
###options
buffer:the buffer which you want to transfer to thread,default is false,create pool may not set it.
poolsize:thread poolsize, set false not use thread pool. default is false;
fastthread:to set false, using nodejs child process, you can use all nodejs module and api.To set true, using quick thread, you only can use js function in it, but more faster.default is true.
dirname:if you want to use require in thread, make sure set the correct dirname.you can also set it by created thread pool like this:
var threadp1 = tagg2.create({poolsize:10,dirname:__dirname});//the thread in pool are all using the same __dirname
notice if fastthread is false,you have the real another node.js process,so you can do anything in it.
###callback(err,res)
every callback has the same parameter
the first argument is error, if some error occur in the thread, the parameter will be not null;
the second argument is result,when thread.end(result) run in the thread, the result will transfer to main thread and execute the callback; thread.end method see below;
###thread
object, you can get thread object from execute tagg2.create(...).
if you set poolsize from tagg2.create(...),like tagg2.create({poolsize:10}),return thread pool object.
###thread.id --not support thread pool
the number mark the thread or child process.
###thread.destory([true]])
destory the thread or thread pool.make sure to execute it when you don't need the thread or pool any more.
ex1. thread.destory();//kill the thread smooth
ex2. thread.destory([true]); //kill the thread or child process immediately,like kill pid
notice: if using pool, once thread.destory called,the pool will destory but not the thread, thread when work finished the thread will auto return to the pool.
###thread.pool(...) --pool only
put some job to the idle thread in the thread pool,if all the thread is working, the job will wait.
ex1. thread.pool(thread_func)
ex2. thread.pool(thread_func, buffer)
ex3. thread.pool(thread_func, callback)
ex4. thread.pool(thread_func, buffer, callback)
###thread.totalThreads() --pool only
returns the number of threads in this pool
ex1. thread.totalThreads();
###thread.idleThreads() --pool only
returns the number of threads in this pool that are currently idle (sleeping)
ex1. thread.idleThreads();
###thread.pendingJobs() --pool only
returns the number of jobs pending
ex1. thread.pendingJobs()
###in the thread or child-process
in every thread or child function,you can use some global objects below;
###thread.id
the number mark the thread or child process.
###thread.buffer --buffer object
object,save the buffer object which has sent from main thread.
###thread.buffer.toString()
return string; to get the buffer to utf-8 string
ex1. thread.buffer.toString();
###thread.nextTick(function)
Asynchronous do a job
ex1. thread.nextTick(function(){
console.log("Asynchronous")
});
###thread.end([prarm])
ex1.thread.end(); return undefined result to main thread callback;
ex2.thread.end(reslut); return array or object or string to main thread callback;
###console.log(param)
print the array or object or string or number etc. to stdio
ex1. console.log("tagg2")
###require(filepath)
load a js file,you can use global object to read or write the Variable in the require file
ex1. require("./tagg2_require.js"); //make sure tagg2_require.js has in the same dir with __dirname,
support "../../" , "./user", "/user".
notice if fastthread is true, the required file not support "moudle.export", please use global.xxxx to share the function or object.
notice. in the fast thread, there is not a really node.js runtime env,you can't require node.js module,so don't do that 'var fs = require("fs");'
###global --in thread's global object
save the global object in the thread like Browser's window.you can set or get some value from it.every thread has it's own global.
###__dirname
the nodejs dir path which filedirname you called create the thread.the pool used the same dirname when you create the pool.
###user fastthread:false
set fastthread to false will use the slow thread, it fact is a real nodejs process,tagg2 use of child.fork() to achieve
all in the thread1's object and functionally
when you set fastthread false, you can use all the api of node.js,There is no limit,tagg2 also provided a process pool.
##more
see /example , /benchmark and /test for more useful code. do test please run node ./test/main_test.js
##future
TAGG2 module has already in experiment,so you may not use it in production.TAGG2 will more stronger and feature-richer.