Подпроцессы

Запуск и управление дочерними процессами, выполнение команд и сбор вывода. Полезно для запуска внешних программ из Deno.

Например, Deno.Command

класс Deno.ChildProcess

реализует AsyncDisposable

Интерфейс для управления дочерним процессом, возвращаемым Deno.Command.spawn.

Свойства

pid: number

только для чтения

status: Promise<CommandStatus>

только для чтения

Промис, который разрешается после завершения дочернего процесса, возвращая его код завершения и сигнал завершения (если есть). Промис никогда не отклоняется; если процесс ещё выполняется, промис остаётся ожидающим. Само по себе обращение к этому свойству не предотвращает завершение процесса Deno — см. ChildProcess.ref.

stderr: SubprocessReadableStream

только для чтения

stdin: WritableStream<Uint8Array<ArrayBufferLike>>

только для чтения

stdout: SubprocessReadableStream

только для чтения

Методы

[Symbol.asyncDispose](): Promise<void>

kill(signo?: Signal | number): void

Завершает процесс, отправляя указанный Deno.Signal или числовой сигнал.

Если сигнал не указан, по умолчанию используется SIGTERM.

output(): Promise<CommandOutput>

Ожидает полного завершения дочернего процесса, возвращая весь его вывод и статус.

ref(): void

Обеспечивает, чтобы статус дочернего процесса препятствовал завершению процесса Deno.

unref(): void

Обеспечивает, чтобы статус дочернего процесса не препятствовал завершению процесса Deno.

класс Deno.Command

allow-run

Создаёт дочерний процесс.

Если для каких-либо параметров stdio установлено значение, отличное от "piped", обращение к соответствующему полю у Command или его CommandOutput приведёт к ошибке TypeError.

Если для stdin установлено значение "piped", stdin WritableStream необходимо закрыть вручную.

Command работает как конструктор. Каждый вызов Command.spawn или Command.output запускает новый подпроцесс.

Примеры

const command = new Deno.Command(Deno.execPath(), {
  args: [
    "eval",
    "console.log('Hello World')",
  ],
  stdin: "piped",
  stdout: "piped",
});
const child = command.spawn();

// open a file and pipe the subprocess output to it.
child.stdout.pipeTo(
  Deno.openSync("output", { write: true, create: true }).writable,
);

// manually close stdin
child.stdin.close();
const status = await child.status;

const command = new Deno.Command(Deno.execPath(), {
  args: [
    "eval",
    "console.log('hello'); console.error('world')",
  ],
});
const { code, stdout, stderr } = await command.output();
console.assert(code === 0);
console.assert("hello\n" === new TextDecoder().decode(stdout));
console.assert("world\n" === new TextDecoder().decode(stderr));

const command = new Deno.Command(Deno.execPath(), {
  args: [
    "eval",
    "console.log('hello'); console.error('world')",
  ],
});
const { code, stdout, stderr } = command.outputSync();
console.assert(code === 0);
console.assert("hello\n" === new TextDecoder().decode(stdout));
console.assert("world\n" === new TextDecoder().decode(stderr));

Конструкторы

Command(

command: string | URL,

options?: CommandOptions,
)

новый

Методы

output(): Promise<CommandOutput>

Выполняет Deno.Command, ожидает его завершения и собирает весь его вывод.

Если задано stdin: "piped", будет выброшена ошибка.

Если для параметров stdout или stderr установлено значение, отличное от "piped", обращение к соответствующему полю в Deno.CommandOutput приведёт к ошибке TypeError.

outputSync(): CommandOutput

Синхронно выполняет Deno.Command, ожидает его завершения и собирает весь его вывод.

Если задано stdin: "piped", будет выброшена ошибка.

spawn(): ChildProcess

Запускает потоковый подпроцесс, позволяя использовать другие методы.

функция Deno.kill

allow-run

kill(

pid: number,

signo?: Signal | number,
): void

Отправляет сигнал процессу с указанным pid. Значение и смысл signal, отправляемого процессу, зависят от операционной системы и процесса. В Signal представлены наиболее распространённые сигналы. Сигнал по умолчанию — "SIGTERM".

Термин kill заимствован из команды командной строки UNIX-подобных систем kill, которая также отправляет сигналы процессам.

Если pid отрицателен, сигнал будет отправлен группе процессов, определяемой pid. При использовании отрицательного pid в Windows будет выброшена ошибка.

const command = new Deno.Command("sleep", { args: ["10000"] });
const child = command.spawn();

Deno.kill(child.pid, "SIGINT");

В качестве особого случая сигнал 0 можно использовать для проверки существования процесса.

Требуется разрешение allow-run.

Параметры

pid: number

signo: Signal | number

необязательный

Тип возвращаемого значения

void

функция Deno.spawn

нестабильный

allow-run

Перегрузка 1

spawn(

command: string | URL,

options?: CommandOptions,
): ChildProcess

Запускает новый подпроцесс и возвращает дескриптор Deno.ChildProcess.

Примеры

const child = Deno.spawn(Deno.execPath(), {
  args: ["eval", "console.log('hello')"],
  stdout: "piped",
});
const output = await child.stdout.text();
console.log(output); // "hello\n"
const status = await child.status;

Параметры

command: string | URL

options: CommandOptions

необязательный

Тип возвращаемого значения

ChildProcess

Перегрузка 2

spawn(

command: string | URL,

args: string[],

options?: Omit<CommandOptions, "args">,
): ChildProcess

Запускает новый подпроцесс с указанными аргументами и возвращает дескриптор Deno.ChildProcess.

Примеры

const child = Deno.spawn(Deno.execPath(), ["eval", "console.log('hello')"], {
  stdout: "piped",
});
const output = await child.stdout.text();
console.log(output); // "hello\n"
const status = await child.status;

Параметры

command: string | URL

args: string[]

options: Omit<CommandOptions, "args">

необязательный

Тип возвращаемого значения

ChildProcess

функция Deno.spawnAndWait

нестабильный

allow-run

Перегрузка 1

spawnAndWait(

command: string | URL,

options?: CommandOptions,
): Promise<CommandOutput>

Запускает подпроцесс, ожидает его завершения и возвращает вывод.

Примеры

const { code, stdout, stderr } = await Deno.spawnAndWait(Deno.execPath(), {
  args: ["eval", "console.log('hello')"],
});
console.log(new TextDecoder().decode(stdout)); // "hello\n"

Параметры

command: string | URL

options: CommandOptions

необязательный

Тип возвращаемого значения

Promise<CommandOutput>

Перегрузка 2

spawnAndWait(

command: string | URL,

args: string[],

options?: Omit<CommandOptions, "args">,
): Promise<CommandOutput>

Запускает подпроцесс с указанными аргументами, ожидает его завершения и возвращает вывод.

Примеры

const { code, stdout } = await Deno.spawnAndWait(
  Deno.execPath(),
  ["eval", "console.log('hello')"],
);
console.log(new TextDecoder().decode(stdout)); // "hello\n"

Параметры

command: string | URL

args: string[]

options: Omit<CommandOptions, "args">

необязательный

Тип возвращаемого значения

Promise<CommandOutput>

функция Deno.spawnAndWaitSync

нестабильный

allow-run

Перегрузка 1

spawnAndWaitSync(

command: string | URL,

options?: CommandOptions,
): CommandOutput

Синхронно запускает подпроцесс, ожидает его завершения и возвращает вывод.

Примеры

const { code, stdout } = Deno.spawnAndWaitSync(Deno.execPath(), {
  args: ["eval", "console.log('hello')"],
});
console.log(new TextDecoder().decode(stdout)); // "hello\n"

Параметры

command: string | URL

options: CommandOptions

необязательный

Тип возвращаемого значения

CommandOutput

Перегрузка 2

spawnAndWaitSync(

command: string | URL,

args: string[],

options?: Omit<CommandOptions, "args">,
): CommandOutput

Синхронно запускает подпроцесс с указанными аргументами, ожидает его завершения и возвращает вывод.

Примеры

const { code, stdout } = Deno.spawnAndWaitSync(
  Deno.execPath(),
  ["eval", "console.log('hello')"],
);
console.log(new TextDecoder().decode(stdout)); // "hello\n"

Параметры

command: string | URL

args: string[]

options: Omit<CommandOptions, "args">

необязательный

Тип возвращаемого значения

CommandOutput

интерфейс Deno.CommandOptions

Параметры, которые можно задать при вызове Deno.Command.

Свойства

args: string[]

необязательное

Аргументы, передаваемые процессу.

cwd: string | URL

необязательное

Рабочий каталог процесса.

Если он не указан, используется cwd родительского процесса.

clearEnv: boolean = false

необязательное

Очищает переменные среды родительского процесса.

Это не гарантирует, что будут присутствовать только переменные env, поскольку ОС может задавать переменные среды для процессов.

env: Record<string, string>

необязательное

Переменные среды, передаваемые дочернему процессу.

uid: number

необязательное

Задаёт идентификатор пользователя дочернего процесса. Это приводит к вызову setuid в дочернем процессе. Если вызов set uid завершится ошибкой, запуск процесса завершится неудачей.

gid: number

необязательное

Подобно uid, но задаёт идентификатор группы дочернего процесса.

signal: AbortSignal

необязательное

AbortSignal, позволяющий закрыть процесс с помощью соответствующего AbortController, отправив процессу сигнал SIGTERM.

Не поддерживается в Deno.Command.outputSync.

stdin: 
"piped"
 | "inherit"
 | "null"

необязательное

Способ обработки stdin запущенного процесса.

По умолчанию используется "inherit" для output и outputSync, а для spawn — "inherit".

stdout: 
"piped"
 | "inherit"
 | "null"

необязательное

Способ обработки stdout запущенного процесса.

По умолчанию используется "piped" для output и outputSync, а для spawn — "inherit".

stderr: 
"piped"
 | "inherit"
 | "null"

необязательное

Способ обработки stderr запущенного процесса.

По умолчанию используется "piped" для output и outputSync, а для spawn — "inherit".

windowsRawArguments: boolean = false

необязательное

Отключает заключение аргументов в кавычки и их экранирование в Windows. Этот параметр игнорируется на платформах, отличных от Windows.

detached: boolean = false

необязательное

Определяет, следует ли отделить запущенный процесс от текущего. Это позволяет запущенному процессу продолжать работу после завершения текущего процесса.

Примечание: чтобы текущий процесс мог завершиться, необходимо убедиться, что для дочернего процесса вызывается unref().

Кроме того, потоки stdio — если они унаследованы или подключены через канал — могут препятствовать завершению текущего процесса до тех пор, пока не будут закрыты.

интерфейс Deno.CommandOutput

расширяет CommandStatus

Интерфейс, возвращаемый при вызове Deno.Command.output или Deno.Command.outputSync и представляющий результат запуска дочернего процесса.

Свойства

stdout: Uint8Array<ArrayBuffer>

только для чтения

Буферизованные выходные данные из stdout дочернего процесса.

stderr: Uint8Array<ArrayBuffer>

только для чтения

Буферизованные выходные данные из stderr дочернего процесса.

интерфейс Deno.CommandStatus

Свойства

success: boolean

Если дочерний процесс завершится с кодом состояния 0, success будет установлено в true, в противном случае — false.

code: number

Код завершения дочернего процесса.

signal: Signal | null

Сигнал, связанный с дочерним процессом.

интерфейс Deno.SubprocessReadableStream

расширяет ReadableStream<Uint8Array<ArrayBuffer>>

Интерфейс потоков stdout и stderr дочернего процесса, возвращаемый из Deno.Command.spawn.

Методы

arrayBuffer(): Promise<ArrayBuffer>

Считывает поток до конца. Возвращает промис, который разрешается значением ArrayBuffer.

bytes(): Promise<Uint8Array<ArrayBuffer>>

Считывает поток до конца. Возвращает промис, который разрешается значением Uint8Array.

json(): Promise<any>

Считывает поток до конца. Возвращает промис, который разрешается результатом разбора текста тела как JSON.

text(): Promise<string>

Считывает поток до конца. Возвращает промис, который разрешается значением USVString (текст).