child_process

Свойство subprocess.channel ссылается на канал IPC дочернего процесса. Если канал IPC отсутствует, это свойство равно undefined.

Свойство subprocess.connected указывает, можно ли по-прежнему отправлять сообщения дочернему процессу и получать их от него. Если subprocess.connected равно false, отправка и получение сообщений больше невозможны.

Свойство subprocess.exitCode указывает код завершения дочернего процесса. Если дочерний процесс всё ещё выполняется, значением поля будет null.

Свойство subprocess.killed указывает, успешно ли дочерний процесс получил сигнал от subprocess.kill(). Свойство killed не указывает на то, что дочерний процесс был завершён.

Возвращает идентификатор процесса (PID) дочернего процесса. Если запуск дочернего процесса не удался из-за ошибок, значением будет undefined и будет сгенерировано событие error.

import { spawn } from 'node:child_process';
const grep = spawn('grep', ['ssh']);

console.log(`Spawned child pid: ${grep.pid}`);
grep.stdin.end();

Свойство subprocess.signalCode указывает сигнал, полученный дочерним процессом, если таковой имеется; в противном случае — null.

Свойство subprocess.spawnargs представляет полный список аргументов командной строки, с которыми был запущен дочерний процесс.

Свойство subprocess.spawnfile указывает имя исполняемого файла запущенного дочернего процесса.

Для fork его значение будет равно process.execPath. Для spawn его значением будет имя исполняемого файла. Для exec его значением будет имя оболочки, в которой запускается дочерний процесс.

Объект Readable Stream, представляющий stderr дочернего процесса.

Если дочерний процесс был запущен с параметром stdio[2], установленным в любое значение, отличное от 'pipe', то это значение будет null.

subprocess.stderr — это псевдоним subprocess.stdio[2]. Оба свойства будут ссылаться на одно и то же значение.

Свойство subprocess.stderr может иметь значение null или undefined, если дочерний процесс не удалось запустить.

Объект Writable Stream, представляющий stdin дочернего процесса.

Если дочерний процесс ожидает чтения всех входных данных, он не продолжит работу, пока этот поток не будет закрыт с помощью end().

Если дочерний процесс был запущен с параметром stdio[0], установленным в любое значение, отличное от 'pipe', то это значение будет null.

subprocess.stdin — это псевдоним subprocess.stdio[0]. Оба свойства будут ссылаться на одно и то же значение.

Свойство subprocess.stdin может иметь значение null или undefined, если дочерний процесс не удалось запустить.

Разреженный массив каналов для дочернего процесса, соответствующих позициям в параметре stdio, переданном в spawn, которым присвоено значение 'pipe'. Значения subprocess.stdio[0], subprocess.stdio[1] и subprocess.stdio[2] также доступны как subprocess.stdin, subprocess.stdout и subprocess.stderr соответственно.

В следующем примере в канал настроен только дескриптор файла 1 дочернего процесса (stdout), поэтому потоком является только subprocess.stdio[1] родительского процесса, а все остальные значения в массиве равны null.

import assert from 'node:assert';
import fs from 'node:fs';
import child_process from 'node:child_process';

const subprocess = child_process.spawn('ls', {
  stdio: [
    0, // Use parent's stdin for child.
    'pipe', // Pipe child's stdout to parent.
    fs.openSync('err.out', 'w'), // Direct child's stderr to a file.
  ],
});

assert.strictEqual(subprocess.stdio[0], null);
assert.strictEqual(subprocess.stdio[0], subprocess.stdin);

assert(subprocess.stdout);
assert.strictEqual(subprocess.stdio[1], subprocess.stdout);

assert.strictEqual(subprocess.stdio[2], null);
assert.strictEqual(subprocess.stdio[2], subprocess.stderr);

Свойство subprocess.stdio может иметь значение undefined, если дочерний процесс не удалось запустить.

Объект Readable Stream, представляющий stdout дочернего процесса.

Если дочерний процесс был запущен с параметром stdio[1], установленным в любое значение, отличное от 'pipe', то это значение будет null.

subprocess.stdout — это псевдоним subprocess.stdio[1]. Оба свойства будут ссылаться на одно и то же значение.

import { spawn } from 'node:child_process';

const subprocess = spawn('ls');

subprocess.stdout.on('data', (data) => {
  console.log(`Received chunk ${data}`);
});

Свойство subprocess.stdout может иметь значение null или undefined, если дочерний процесс не удалось запустить.

Вызывает ChildProcess.kill с аргументом 'SIGTERM'.

events.EventEmitter

1. close
2. disconnect
3. error
4. exit
5. message
6. spawn

Закрывает канал IPC между родительским и дочерним процессами, позволяя дочернему процессу корректно завершиться, если нет других соединений, удерживающих его. После вызова этого метода свойства subprocess.connected и process.connected родительского и дочернего процессов (соответственно) будут установлены в false, и передавать сообщения между процессами станет невозможно.

Событие 'disconnect' будет сгенерировано, когда не останется сообщений, которые находятся в процессе получения. Обычно оно генерируется сразу после вызова subprocess.disconnect().

Если дочерний процесс является экземпляром Node.js (например, запущен с помощью fork), метод process.disconnect() можно вызвать и в дочернем процессе, чтобы также закрыть канал IPC.

Метод subprocess.kill() отправляет сигнал дочернему процессу. Если аргумент не указан, процессу будет отправлен сигнал 'SIGTERM'. Список доступных сигналов см. в разделе signal(7). Эта функция возвращает true, если вызов kill(2) выполнен успешно, и false в противном случае.

import { spawn } from 'node:child_process';
const grep = spawn('grep', ['ssh']);

grep.on('close', (code, signal) => {
  console.log(
    `child process terminated due to receipt of signal ${signal}`);
});

// Send SIGHUP to process.
grep.kill('SIGHUP');

Объект ChildProcess может сгенерировать событие 'error', если сигнал не удастся доставить. Отправка сигнала уже завершившемуся дочернему процессу не является ошибкой, но может привести к непредвиденным последствиям. В частности, если идентификатор процесса (PID) был повторно присвоен другому процессу, сигнал будет отправлен этому процессу, что может привести к неожиданным результатам.

Хотя функция называется kill, отправленный дочернему процессу сигнал может фактически не завершить процесс.

Справочную информацию см. в разделе kill(2).

В Windows, где сигналов POSIX не существует, аргумент signal игнорируется, а процесс принудительно и немедленно завершается (аналогично 'SIGKILL'). Дополнительные сведения см. в Signal Events.

В Linux дочерние процессы дочерних процессов не завершаются при попытке завершить родительский процесс. Такое может произойти при запуске нового процесса в оболочке или с использованием параметра shell метода ChildProcess:

'use strict';
import { spawn } from 'node:child_process';

const subprocess = spawn(
  'sh',
  [
    '-c',
    `node -e "setInterval(() => {
      console.log(process.pid, 'is alive')
    }, 500);"`,
  ], {
    stdio: ['inherit', 'inherit', 'inherit'],
  },
);

setTimeout(() => {
  subprocess.kill(); // Does not terminate the Node.js process in the shell.
}, 2000);

Вызов subprocess.ref() после вызова subprocess.unref() восстановит удалённый счётчик ссылок дочернего процесса, заставив родительский процесс ожидать завершения дочернего, прежде чем завершиться самому.

import { spawn } from 'node:child_process';

const subprocess = spawn(process.argv[0], ['child_program.js'], {
  detached: true,
  stdio: 'ignore',
});

subprocess.unref();
subprocess.ref();

Если между родительским и дочерним процессами установлен канал IPC (то есть при использовании fork), метод subprocess.send() можно использовать для отправки сообщений дочернему процессу. Если дочерний процесс является экземпляром Node.js, эти сообщения можно получить через событие 'message'.

Сообщение проходит сериализацию и разбор. Полученное сообщение может отличаться от исходного.

Например, в родительском скрипте:

import cp from 'node:child_process';
const n = cp.fork(`${__dirname}/sub.js`);

n.on('message', (m) => {
  console.log('PARENT got message:', m);
});

// Causes the child to print: CHILD got message: { hello: 'world' }
n.send({ hello: 'world' });

А дочерний скрипт, 'sub.js', может выглядеть так:

process.on('message', (m) => {
  console.log('CHILD got message:', m);
});

// Causes the parent to print: PARENT got message: { foo: 'bar', baz: null }
process.send({ foo: 'bar', baz: NaN });

У дочерних процессов Node.js есть собственный метод process.send(), позволяющий дочернему процессу отправлять сообщения родительскому.

Особый случай — отправка сообщения {cmd: 'NODE_foo'}. Сообщения, содержащие префикс NODE_ в свойстве cmd, зарезервированы для внутреннего использования в ядре Node.js и не будут генерироваться как событие 'message' дочернего процесса. Вместо этого такие сообщения генерируются как событие 'internalMessage' и обрабатываются внутри Node.js. Приложениям следует избегать отправки таких сообщений и прослушивания событий 'internalMessage', поскольку их поведение может измениться без предупреждения.

Необязательный аргумент sendHandle, который можно передать в subprocess.send(), предназначен для передачи дочернему процессу объекта TCP-сервера или сокета. Дочерний процесс получит этот объект в качестве второго аргумента функции обратного вызова, зарегистрированной для события 'message'. Данные, полученные и буферизованные сокетом, дочернему процессу отправлены не будут. Передача сокетов IPC в Windows не поддерживается.

Необязательный аргумент callback — это функция, вызываемая после отправки сообщения, но до того, как дочерний процесс может его получить. Функция вызывается с одним аргументом: null в случае успеха или объектом Error в случае ошибки.

Если функция callback не указана и сообщение не удаётся отправить, объект ChildProcess сгенерирует событие 'error'. Такое может произойти, например, если дочерний процесс уже завершился.

Метод subprocess.send() вернёт false, если канал закрыт или очередь неотправленных сообщений превысила порог, после которого отправка дополнительных сообщений становится нежелательной. В противном случае метод возвращает true. Для реализации управления потоком можно использовать функцию callback.

Пример: отправка объекта сервера

Аргумент sendHandle можно использовать, например, для передачи дескриптора объекта TCP-сервера дочернему процессу, как показано в примере ниже:

import { createServer } from 'node:net';
import { fork } from 'node:child_process';
const subprocess = fork('subprocess.js');

// Open up the server object and send the handle.
const server = createServer();
server.on('connection', (socket) => {
  socket.end('handled by parent');
});
server.listen(1337, () => {
  subprocess.send('server', server);
});

Затем дочерний процесс получит объект сервера следующим образом:

process.on('message', (m, server) => {
  if (m === 'server') {
    server.on('connection', (socket) => {
      socket.end('handled by child');
    });
  }
});

После того как сервер станет общим для родительского и дочернего процессов, часть соединений сможет обрабатывать родительский процесс, а часть — дочерний.

В приведённом выше примере используется сервер, созданный с помощью модуля node:net. Серверы модуля node:dgram работают точно так же, за исключением того, что вместо события 'connection' нужно ожидать событие 'message', а вместо server.listen() использовать server.bind(). Однако такая возможность поддерживается только на платформах Unix.

Пример: отправка объекта сокета

Аналогичным образом аргумент sendHandler можно использовать для передачи дочернему процессу дескриптора сокета. В примере ниже запускаются два дочерних процесса, каждый из которых обрабатывает соединения с «обычным» или «высоким» приоритетом:

import { createServer } from 'node:net';
import { fork } from 'node:child_process';
const normal = fork('subprocess.js', ['normal']);
const special = fork('subprocess.js', ['special']);

// Open up the server and send sockets to child. Use pauseOnConnect to prevent
// the sockets from being read before they are sent to the child process.
const server = createServer({ pauseOnConnect: true });
server.on('connection', (socket) => {

  // If this is special priority...
  if (socket.remoteAddress === '74.125.127.100') {
    special.send('socket', socket);
    return;
  }
  // This is normal priority.
  normal.send('socket', socket);
});
server.listen(1337);

subprocess.js получит дескриптор сокета в качестве второго аргумента функции обратного вызова события:

process.on('message', (m, socket) => {
  if (m === 'socket') {
    if (socket) {
      // Check that the client socket exists.
      // It is possible for the socket to be closed between the time it is
      // sent and the time it is received in the child process.
      socket.end(`Request handled with ${process.argv[2]} priority`);
    }
  }
});

Не используйте .maxConnections для сокета, переданного подпроцессу. Родительский процесс не может отследить момент уничтожения сокета.

Обработчики 'message' в подпроцессе должны проверять наличие socket, поскольку соединение может быть закрыто за время, необходимое для передачи соединения дочернему процессу.

По умолчанию родительский процесс ожидает завершения отсоединённого дочернего процесса. Чтобы родительский процесс не ожидал завершения заданного subprocess, используйте метод subprocess.unref(). В результате дочерний процесс не будет учитываться в счётчике ссылок цикла событий родительского процесса, что позволит родительскому процессу завершиться независимо от дочернего, если между ними не установлен канал IPC.

import { spawn } from 'node:child_process';

const subprocess = spawn(process.argv[0], ['child_program.js'], {
  detached: true,
  stdio: 'ignore',
});

subprocess.unref();