https://github.com/little-core-labs/nanoprocess
Maintain a child process as a nanoresource
https://github.com/little-core-labs/nanoprocess
child nanoresource process
Last synced: 4 months ago
JSON representation
Maintain a child process as a nanoresource
- Host: GitHub
- URL: https://github.com/little-core-labs/nanoprocess
- Owner: little-core-labs
- License: mit
- Created: 2019-10-26T16:58:20.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2020-03-17T17:09:36.000Z (about 5 years ago)
- Last Synced: 2024-12-29T21:35:33.326Z (4 months ago)
- Topics: child, nanoresource, process
- Language: JavaScript
- Size: 113 KB
- Stars: 6
- Watchers: 6
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
nanoprocess
===========
> Maintain a child process as a [nanoresource][nanoresource]
```sh
$ npm install nanoprocess
```
> **Stable**
> [](https://github.com/little-core-labs/nanoprocess/actions)
```js
const nanoprocess = require('nanoprocess')
// spawn a comand
const child = nanoprocess(command, args, opts)
// open process and query for stats
child.open((err) => {
child.stat((err, stats) => {
console.log(stats)
})
})
```
The following example spawns a node process that spawns a `sleep`
command running for 2 seconds while also doing a lot of work
(`Array(10e7).fill(crypto.randomBytes(1024));`). The example will query
for process stats and leverage the [progress][progress] module to output
process memory and CPU usage.
```js
const prettyBytes = require('pretty-bytes')
const nanoprocess = require('nanoprocess')
const prettyTime = require('pretty-ms')
const Progress = require('progress')
const template = [
'> :name (:pid)',
'up for :uptime',
'CPU: :cpu%',
'MEM: :mem',
':pidsCount child process(es)'
].join(' | ')
const sleep = nanoprocess('node', [
'-e',
'process.title = "sleep";' +
'require("cross-spawn")("sleep", [2]);' +
'Array(10e7).fill(crypto.randomBytes(1024));'
])
const bar = new Progress(template, {
width: 20,
total: 1
})
sleep.open((err) => {
console.log('> opened')
let timer = 0
sleep.stat(function onstat(err, stats) {
if (stats) {
bar.update(0, {
pidsCount: stats.pids.length,
uptime: prettyTime(stats.uptime),
name: stats.name,
mem: prettyBytes(stats.memory),
cpu: Math.floor(stats.cpu),
pid: stats.pid,
})
}
if (stats && stats.uptime > 2000 && 0 === stats.cpu) {
bar.update(1, stats)
sleep.close()
} else if (!err) {
clearTimeout(timer)
timer = setTimeout(() => sleep.stat(onstat), 100)
}
})
sleep.process.on('close', () => {
console.log('')
console.log('> closed')
})
})
```
```sh
$ node example.js
> opened
> sleep (33153) | up for 5.2s | CPU: 99% | MEM: 1.25 GB | 1 child process(es)
> closed
```
### `const nanoprocess = require('nanoprocess')`
The `nanoprocess` function returns a new [`Process`](#child-process) instance
that extends [nanoresource][nanoresource].
```js
const child = nanoprocess('sleep', [2])
child.open((err) => {
// process is opened
})
```
### `const child = nanoprocess(command[, args[, options]])`
Create a new [`Process`](#child-process) instance from `command` with
optional `args` and `options` that are given to
[cross-spawn][cross-spawn] when the [child process is
opened](#child-open).
```js
const ls = nanoprocess('ls', ['.'])
ls.open((err) => {
ls.process.stdout.pipe(process.stdout)
})
```
### `const { Process } = require('nanoprocess')`
The `nanoprocess` exports the [`Process`](#child-process) class that can
be extended.
```js
const { Process } = require('nanoprocess')
class InstallDependencies extends Process {
constructor(dirname) {
super('npm', ['install'], { cwd: dirname })
}
}
const install = new InstallDependencies('path/to/dir')
install.open(() => {
// stat loop
install.stat(function onstat(err, stats) {
console.log(stats) // Stats { cpu: 14.23, ... }
install.stat(onstat)
})
install.process.on('close', (err) => {
console.log('closed')
})
})
```
### `const child = new Process(command[, args[, options]])`
Create a new [`Process`](#child-process) instance from `command` with
optional `args` and `options` that are given to
[cross-spawn][cross-spawn] when the [child process is
opened](#child-open).
The initial `options` given to the [`Process`](#child-process) instance
constructor which are given to [cross-spawn][cross-spawn] when
the [child process is opened](#child-open).
The command to [spawn][cross-spawn] when the
[child process is opened](#child-open).
When the child process is opened, this will be an instance of
[`child_process.ChildProcess`](
https://nodejs.org/api/child_process.html#child_process_class_childprocess).
The child process ID.
The child process parent process ID.
The child process `stdin` stream. This may be `null`.
The child process `stdout` stream. This may be `null`.
The child process `stderr` stream. This may be `null`.
The child process `channel` object. This may be `null`.
The child process connection state.
The child process killed state.
The child process exit signal. This value can be `null`. Check this
after the child process has closed.
The child process exit code. This value can be `null`. Check this after
the child process has closed.
The arguments for the child process [command](#child-command) given to
[cross-spawn][cross-spawn] when the [child process is opened](#child-open).
Opens the child process by [spawning][cross-spawn] a
[command](#child-command) with optional [arguments](#child-args) and
[options](#child-options) calling `callback(err)` when opened or if an
error occurs during the spawning of the child process.
#### `child.close([allowActive[, callback]])`
Closes the child process and all decedent child process in the process
tree calling `callback(err)` when closed or if an error occurs during
the closing of the spawned child process. Setting `allowActive` to
`false` (default) will cause a `'SIGTERM'` to be sent to the child process
causing it to close. You can call `child.kill({ force: true })` prior to
calling this method if you want force the processed to be killed. Set
`allowActive` to `true` to wait for the process to close on its and mark
the [nanoresource][nanoresource] instance **inactive**.
#### `child.kill([opts], callback)`
Kill the child process calling `callback` when killed or if can error
occurs. Set `opts.true` to force the processed to be killed.
Queries for statistics about the running child process for information
like [cpu usage](#child-stat-cpu) and [memory
consumption](#child-stat-memory) calling `callback(err, stats)` with a
stats object or if an error occurs.
```js
child.stat((err, stats) => {
// handle stats
})
```
The output of the `stats` object may look something like:
```js
Stats {
bin: 'sleep',
uid: 1000,
gid: 1000,
cpu: 138.46153845657875,
pid: 33792,
ppid: 33785,
pids: [ 33810 ],
name: 'sleep',
atime: 1572118184405,
uptime: 680,
memory: 241070080,
command: 'node' }
```
The initial binary used invoke the child process.
The user ID of the child process.
The group ID of the child process.
The current CPU usage as a percentage of the child process.
The child process ID.
The parent process ID of the child process.
The child process IDs of the child process
The name of process
The time stamp in milliseconds this stat was accessed.
Time in milliseconds since process spawned
Memory usage in bytes
The command used to start the process
`true` if the process or any child process in the [pidtree][pidtree] for
the root child process [is still running][is-running].
## See Also
- [nanoresource][nanoresource]
- [find-process][find-process]
- [cross-spawn][cross-spawn]
- [pidusage][pidusage]
- [pidtree][pidtree]
## License
MIT
[nanoresource]: https://github.com/mafintosh/nanoresource
[find-process]: https://github.com/yibn2008/find-process
[cross-spawn]: https://github.com/moxystudio/node-cross-spawn
[is-running]: https://github.com/nisaacson/is-running
[progress]: https://github.com/visionmedia/node-progress
[pidusage]: https://github.com/soyuka/pidusage
[pidtree]: https://github.com/simonepri/pidtree