init

.gitignore

@@ -0,0 +1,8 @@
+
+.DS_Store*
+*.log
+*.gz
+
+node_modules
+coverage
+cache

.travis.yml

@@ -0,0 +1,8 @@
+node_js:
+- "0.8"
+- "0.10"
+- "0.11"
+language: node_js
+script: "npm run-script test-travis"
+before_install: "npm update -g npm"
+after_script: "npm install coveralls@2 && cat ./coverage/lcov.info | coveralls"

LICENSE

@@ -0,0 +1,22 @@
+
+The MIT License (MIT)
+
+Copyright (c) 2014 Jonathan Ong [email protected]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,100 @@
+
+# slave
+
+[![NPM version][npm-image]][npm-url]
+[![Build status][travis-image]][travis-url]
+[![Test coverage][coveralls-image]][coveralls-url]
+[![Dependency Status][david-image]][david-url]
+[![License][license-image]][license-url]
+[![Downloads][downloads-image]][downloads-url]
+[![Gittip][gittip-image]][gittip-url]
+
+Slave is a tiny utility to allow you to create long-running slave processes
+for your node process and use these functions as promises.
+Create modules that run in separate processes without anyone even knowing!
+
+## Walkthrough
+
+Wrap your function in a slave.
+The function must either:
+
+- Be a [co](https://github.com/visionmedia/co)-based generator function
+- A function that returns a promise
+- A synchronous function
+
+Now, create a separate `my-module/slave.js` file:
+
+```js
+var slave = require('slave/slave');
+var fn = require('./index.js'); // my main module
+slave(fn); // it's wrapped!
+```
+
+Now you can create a `my-module/master.js` file,
+which runs `slave.js`:
+
+```js
+var master = require('slave/master');
+module.exports = master(require.resolve('./slave.js'))
+```
+
+Now users have two ways to use this module.
+Directly:
+
+```js
+var fn = require('my-module');
+
+fn(1, 2).then(function (val) {
+
+});
+```
+
+Using child processes:
+
+```js
+var fn = require('my-module/master');
+
+fn(1, 2).then(function (val) {
+
+});
+```
+
+## API
+
+### var fn = slave.master(slavepath, [options])
+
+
+Create a function from a `slavepath`,
+which exports a `slave.slave()` function.
+
+Options are:
+
+- `forks=0` - number of child processes to initiate immediately
+
+`fn` will __always__ return a promise,
+even if the wrapped function is synchronous.
+
+### fn.fork()
+
+Create a new child process.
+
+### slave.slave(fn)
+
+Hooks a function into `process` to allow the parent process to listen.
+
+[npm-image]: https://img.shields.io/npm/v/slave.svg?style=flat-square
+[npm-url]: https://npmjs.org/package/slave
+[github-tag]: http://img.shields.io/github/tag/thenables/slave.svg?style=flat-square
+[github-url]: https://github.com/thenables/slave/tags
+[travis-image]: https://img.shields.io/travis/thenables/slave.svg?style=flat-square
+[travis-url]: https://travis-ci.org/thenables/slave
+[coveralls-image]: https://img.shields.io/coveralls/thenables/slave.svg?style=flat-square
+[coveralls-url]: https://coveralls.io/r/thenables/slave?branch=master
+[david-image]: http://img.shields.io/david/thenables/slave.svg?style=flat-square
+[david-url]: https://david-dm.org/thenables/slave
+[license-image]: http://img.shields.io/npm/l/slave.svg?style=flat-square
+[license-url]: LICENSE
+[downloads-image]: http://img.shields.io/npm/dm/slave.svg?style=flat-square
+[downloads-url]: https://npmjs.org/package/slave
+[gittip-image]: https://img.shields.io/gittip/jonathanong.svg?style=flat-square
+[gittip-url]: https://www.gittip.com/jonathanong/

index.js

@@ -0,0 +1,3 @@
+
+exports.master = require('./master')
+exports.slave = require('./slave')

master.js

@@ -0,0 +1,81 @@
+
+var Promise = require('native-or-bluebird')
+var cp = require('child_process')
+
+var slice = [].slice
+
+module.exports = Master
+
+function Master(filename, options) {
+  options = options || {}
+  var slaves = []
+  var _id = 0
+
+  // create a new child process
+  runner.fork = function () {
+    var n = cp.fork(filename)
+    n.queue = 0
+    slaves.push(n)
+  }
+
+  if (typeof options.forks === 'number') {
+    var forks = options.forks
+    while (forks--) runner.fork()
+  }
+
+  // kill all child processes
+  runner.kill = function (signal) {
+    var slave
+    while (slave = slaves.shift()) slave.kill(signal)
+  }
+
+  // get the cp with the lowest queue
+  runner.select = function () {
+    var slave
+    var selected
+    var min = Infinity
+    for (var i = 0; i < slaves.length; i++) {
+      slave = slaves[i]
+      if (slave.queue === 0) return slave
+      if (slave.queue < min) {
+        selected = slave
+        min = slave.queue
+      }
+    }
+    if (selected) return selected
+    throw new Error('no child processes!')
+  }
+
+  return runner
+
+  function runner() {
+    var args = slice.call(arguments)
+    var proc = runner.select()
+    proc.queue++
+    var id = _id++
+
+    return new Promise(function (resolve, reject) {
+      proc.on('message', function onmessage(res) {
+        if (res.id !== id) return
+        proc.queue--
+        proc.removeListener('message', onmessage)
+        if ('value' in res) return resolve(res.value)
+        else reject(JSONToError(res.error))
+      })
+
+      proc.send({
+        id: id,
+        args: args,
+      })
+    })
+  }
+}
+
+function JSONToError(obj) {
+  var err = new Error(obj.message)
+  Object.keys(obj).forEach(function (key) {
+    if (key === 'message') return
+    err[key] = obj[key]
+  })
+  return err
+}

package.json

@@ -0,0 +1,40 @@
+{
+  "name": "slave",
+  "description": "seamlessly create long-running child processes",
+  "version": "0.0.0",
+  "author": {
+    "name": "Jonathan Ong",
+    "email": "[email protected]",
+    "url": "http://jongleberry.com",
+    "twitter": "https://twitter.com/jongleberry"
+  },
+  "license": "MIT",
+  "repository": "thenables/slave",
+  "dependencies": {
+    "native-or-bluebird": "1",
+    "awaitable": "1",
+    "is-generator": "1"
+  },
+  "devDependencies": {
+    "bluebird": "2",
+    "istanbul": "0",
+    "mocha": "1"
+  },
+  "scripts": {
+    "test": "mocha --reporter spec",
+    "test-cov": "istanbul cover node_modules/mocha/bin/_mocha -- --reporter dot",
+    "test-travis": "istanbul cover node_modules/mocha/bin/_mocha --report lcovonly -- --reporter dot"
+  },
+  "keywords": [
+    "slave",
+    "child",
+    "process",
+    "worker",
+    "thread"
+  ],
+  "files": [
+    "index.js",
+    "slave.js",
+    "master.js"
+  ]
+}

slave.js

@@ -0,0 +1,51 @@
+
+var co = require('awaitable')
+var isGenFun = require('is-generator').fn
+
+module.exports = function (fn) {
+  if (isGenFun(fn)) fn = co.wrap(fn)
+
+  process.on('message', function (m) {
+    var thing
+    try {
+      thing = fn.apply(null, m.args)
+    } catch (err) {
+      process.send({
+        id: m.id,
+        error: errorToJSON(err),
+      })
+      return
+    }
+
+    if (!isPromise(thing)) return process.send({
+      id: m.id,
+      value: thing,
+    })
+
+    thing.then(function (val) {
+      process.send({
+        id: m.id,
+        value: val
+      })
+    }, function (err) {
+      process.send({
+        id: m.id,
+        error: errorToJSON(err),
+      })
+    })
+  })
+}
+
+function isPromise(x) {
+  return x && typeof x.then === 'function'
+}
+
+function errorToJSON(err) {
+  var obj = {}
+  Object.keys(err).forEach(function (key) {
+    obj[key] = err[key]
+  })
+  obj.message = err.message
+  obj.stack = err.stack
+  return obj
+}

test/fixtures/add.js

@@ -0,0 +1,4 @@
+
+require('../../slave')(function (a, b, c) {
+  return a + b + c
+})

test/fixtures/error.js

@@ -0,0 +1,4 @@
+
+require('../../slave')(function () {
+  throw new Error('boom')
+})

test/fixtures/promise.js

@@ -0,0 +1,10 @@
+
+var Promise = require('native-or-bluebird')
+
+require('../../slave')(function (val) {
+  return new Promise(function (resolve) {
+    setTimeout(function () {
+      resolve(val)
+    }, Math.round(Math.random() * 10))
+  })
+})

test/fixtures/reject.js

@@ -0,0 +1,6 @@
+
+var Promise = require('native-or-bluebird')
+
+require('../../slave')(function (val) {
+  return Promise.reject(new Error('haha'))
+})

test/fixtures/sync.js

@@ -0,0 +1,4 @@
+
+require('../../slave')(function (val) {
+  return val
+})