Small yet powerful promises based on fibers.
JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
README.md
fibers-promise.js Fixed for new Fibers API Jan 17, 2013
package.json

README.md

Introduction

fibers-promise is a small yet powerful library based on fibers.

A promise is just a value container with build-in synchronisation mechanism. Promises allow you to get rid of callbacks clutter.

You may also like fiberize.

Getting started

npm install fibers-promise

This will install node-fibers as well. (Working g++ and node headers are required.)

Then run your code with:

node-fibers your_file.js

Example

To fetch an url:

var http = require('http');
var promise = require('fibers-promise');

promise.start(function() {

  var p = promise();

  http.get({
      host: 'www.google.com',
      port: 80,
      path: '/'
  }, p);

  var res = p.get();
  res.setEncoding('utf8');
  res.on('data', p);
  res.on('end', p);

  var data, chunk;
  while (chunk = p.get()) {
    data += chunk;
  }
  console.log(data);
});

Interface

var promise = require('fibers-promise');

promise()

promise is a factory method returning new Promise object with the following methods:

  • Promise.set(value)

    set method sets the promise value and resumes a fiber waiting for it (if any).

  • Promise(...)

    Promise object is itself a function which when called sets promise value like a set method. If more than a single value is provided, promise value is set to an array containing all provided values. Thus it's possible to pass promise just as a callback to the asynchronous function.

  • Promise.get()

    Waits until the promise has a value and returns the value.

  • Promise.ready()

    Checks if promise has a value already. Returns a boolean.

  • Promise.wait()

    Waits until a promise has a value.

promise.t()

This is also a factory method similar to promise(), but the get() method of this promise behaves as follows:

  • Single argument has been provided to Promise(...)

    If the value evaluates to true it's thrown; nothing is returned.

  • Two arguments were provided to Promise(...)

    If the first value evaluates to true it's thrown, second value is returned.

  • Three or more arguments were provided to Promise(...)

    If the first value evaluates to true it's thrown; remaining values are returned in form of an Array.

This type of promise is useful when passed as callback to most node asynchronous methods.

promise.start(f, [args...])

start runs f in a new fiber and passes args to f.

promise.task(f)

Returns a function which will execute f in new fiber upon invocation. All the arguments of the returned function are passed directly to f. Useful to postpone start of a fiber, or wrap a callback with a fiber.

promise.waitAny(...)

Waits for multiple promises, the first promise which has a value is returned.

promise.waitAll(...)

Waits until all provided promises have values.

promise.sleep(ms)

Suspends current fiber for ms miliseconds. Does not block the event loop, thus other fibers may execute.