background-process
v1.0.0
Published
Run a process in the background, disconnected from the main process.
Downloads
87
Readme
background-process
Run a process in the background, disconnected from the main process.
Install
Install with npm:
$ npm install --save background-process
Install with yarn:
$ yarn add background-process
Usage
The api has two methods that can be used. The first method is .start and should be used in an application that runs the background script. This application is the runner.
The second method is .ready and should be used inside background scripts to know when they should start executing. The runner will use process.send
to send an options
object to the background script. The options
object is passed as the second argument to the callback function passed to .ready.
The .ready method is not required to be used in the background script since the runner will "fire and forget" when it sends the options
object. It's recommended to use .ready since it'll be easier to configure your background scripts.
Runner
This is an example of running a background script called my-script.js
and passing an options
object.
var background = require('background-process');
// start a background script and pass options to the script
var options = { foo: 'bar' };
background.start('my-script.js', options);
Script
This is an example of a background script called my-script.js
that was passed an options
object.
var background = require('background-process');
// wait for the options to be sent from the runner
background.ready(function(err, options) {
if (err) return console.error(err);
console.log(options);
});
One thing to note is that the stdio
streams are not available in this example since the runner disconnects from the background script. To setup stdio
streams for the background script, they may be specified on the options
object as an array:
// setup stdio streams for the background script to write to
var stdout = fs.openSync('path/to/stdout.txt', 'a');
var stderr = fs.openSync('path/to/stderr.txt', 'a');
var options = { stdio: [stdout, stderr] };
background.start('my-script.js', options);
See the example for more information.
API
.start
Start a background script and send the new child process the given options before disconnecting from the child process.
Params
fp
{String}: filepath to the background scriptoptions
{Object}: Additional options to send to the child processreturns
{Number}: Returns the child process ID.
Example
background.start('worker.js', { timeout: 5000 });
.ready
Use in a child script to know when to start running. The callback function will recieve a possible Error
object and an options
object. This is a wrapper for doing process.on('message', ...)
. This is not something that's required since the runner process will not wait for a response and disconnect. This is a way to send options from the runner to the background script.
Params
cb
{Function}: Callback function that will be executed when the options are recieved from the runner.
Example
background.ready(function(err, options) {
if (err) return;
// do something
});
Acknowledgements
My main goal was to run background scripts from a parent process and still let the parent process exit before the background process finished. In researching how to achieve my goal, I learned a lot from code in forever and forever-monitor.
About
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Please read the contributing guide for advice on opening issues, pull requests, and coding standards.
Building docs
(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command:
$ npm install -g verbose/verb#dev verb-generate-readme && verb
Running tests
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
$ npm install && npm test
Author
Brian Woodward
License
Copyright © 2017, Brian Woodward. Released under the MIT License.
This file was generated by verb-generate-readme, v0.6.0, on May 08, 2017.