node-fibers

NOTE OF OBSOLESCENCE -- The author of this project recommends you avoid its use if possible. The original version of this module targeted nodejs v0.1.x in early 2011 when JavaScript on the server looked a lot different. Since then async/await, Promises, and Generators were standardized and the ecosystem as a whole has moved in that direction. I'll continue to support newer versions of nodejs as long as possible but v8 and nodejs are extraordinarily complex and dynamic platforms. It is inevitable that one day this library will abruptly stop working and no one will be able to do anything about it. I'd like to say thank you to all the users of fibers, your support over the years has meant a lot to me. Update [April 13th, 2021] -- Fibers is not compatible with nodejs v16.0.0 or later. Unfortunately, v8 commit dacc2fee0f is a breaking change and workarounds are non-trivial. fibers(1) -- Fiber support for v8 and Node Fibers, sometimes called coroutines, are a powerful tool which expose an API to jump between multiple call stacks from within a single thread. This can be useful to make code written for a synchronous library play nicely in an asynchronous environment. INSTALLING via npm npm install fibers You're done! (see "supported platforms" below if you run into errors) from source git clone git://github.com/laverdet/node-fibers.git cd node-fibers npm install Note: node-fibers uses node-gyp for building. To manually invoke the build process, you can use node-gyp rebuild. This will put the compiled extension in build/Release/fibers.node. However, when you do require('fibers'), it will expect the module to be in, for example, bin/linux-x64-v8-3.11/fibers.node. You can manually put the module here every time you build, or you can use the included build script. Either npm install or node build -f will do this for you. If you are going to be hacking on node-fibers, it may be worthwhile to first do node-gyp configure and then for subsequent rebuilds you can just do node-gyp build which will be faster than a full npm install or node-gyp rebuild. meteor users please read this If you're trying to get meteor running and you ended up at this page you're probably doing something wrong. Please uninstall all versions of NodeJS and Meteor, then start over. See meteor#5124 for more information. supported platforms If you are running 64-bit nodejs version 12.x or 14.x on Linux, OS X, or Windows (7 or later) then you should be able to install fibers from npm just fine. If you are running nodejs v10.x then you will need to use npm install fibers@4. Older versions of nodejs will require older and older version of fibers. (special thanks to Jeroen Janssen for his work on fibers in Windows) If you do end up needing to compile fibers first make sure you have node-gyp installed as a global dependency (npm install -g node-gyp), and that you have setup your build environment by following the instructions at node-gyp. Ubuntu-flavored Linux users may need to run sudo apt-get install g++ as well. EXAMPLES The examples below describe basic use of Fiber, but note that it is not recommended to use Fiber without an abstraction in between your code and fibers. See "FUTURES" below for additional information. Sleep This is a quick example of how you can write sleep() with fibers. Note that while the sleep() call is blocking inside the fiber, node is able to handle other events. $ cat sleep.js var Fiber = require('fibers'); function sleep(ms) { var fiber = Fiber.current; setTimeout(function() { fiber.run(); }, ms); Fiber.yield(); } Fiber(function() { console.log('wait... ' + new Date); sleep(1000); console.log('ok... ' + new Date); }).run(); console.log('back in main'); $ node sleep.js wait... Fri Jan 21 2011 22:42:04 GMT+0900 (JST) back in main ok... Fri Jan 21 2011 22:42:05 GMT+0900 (JST) Incremental Generator Yielding execution will resume back in the fiber right where you left off. You can also pass values back and forth through yield() and run(). Again, the node event loop is never blocked while this script is running. $ cat generator.js var Fiber = require('fibers'); var inc = Fiber(function(start) { var total = start; while (true) { total += Fiber.yield(total); } }); for (var ii = inc.run(1); ii <= 10; ii = inc.run(1)) { console.log(ii); } $ node generator.js 1 2 3 4 5 6 7 8 9 10 Fibonacci Generator Expanding on the incremental generator above, we can create a generator which returns a new Fibonacci number with each invocation. You can compare this with the ECMAScript Harmony Generator Fibonacci example. $ cat fibonacci.js var Fiber = require('fibers'); // Generator function. Returns a function which returns incrementing // Fibonacci numbers with each call. function Fibonacci() { // Create a new fiber which yields sequential Fibonacci numbers var fiber = Fiber(function() { Fiber.yield(0); // F(0) -> 0 var prev = 0, curr = 1; while (true) { Fiber.yield(curr); var tmp = prev + curr; prev = curr; curr = tmp; } }); // Return a bound handle to `run` on this fiber return fiber.run.bind(fiber); } // Initialize a new Fibonacci sequence and iterate up to 1597 var seq = Fibonacci(); for (var ii = seq(); ii <= 1597; ii = seq()) { console.log(ii); } $ node fibonacci.js 0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 Basic Exceptions Fibers are exception-safe; exceptions will continue travelling through fiber boundaries: $ cat error.js var Fiber = require('fibers'); var fn = Fiber(function() { console.log('async work here...'); Fiber.yield(); console.log('still working...'); Fiber.yield(); console.log('just a little bit more...'); Fiber.yield(); throw new Error('oh crap!'); }); try { while (true) { fn.run(); } } catch(e) { console.log('safely caught that error!'); console.log(e.stack); } console.log('done!'); $ node error.js async work here... still working... just a little bit more... safely caught that error! Error: oh crap! at error.js:11:9 done!