nish:process

The process and its host: exit, the environment, children, signals, the clocks, scheduling, and the size of the machine.

import {
  arch,
  argv,
  availableParallelism,
  exit,
  getenv,
  kill,
  monotonicNanos,
  platform,
  readSignal,
  setCpuAffinity,
  setIdlePriority,
  setNice,
  signalFd,
  spawn,
  spawnPiped,
  spawnPipedWithin,
  spawnSync,
  spawnSyncTo,
  spawnWithFds,
  totalMemory,
  waitPid,
  wallClockNanos,
} from "nish:process";
import { spawn, waitPid, kill, availableParallelism } from "nish:process";

const pid = spawn(["sleep", "5"]);
if (pid > 0) {
  kill(pid, 15);
  const done = waitPid(pid, 0);
}
const workers = availableParallelism();

Each export is the global of the same name, renamed: the compiler emits the same IR for either spelling. A call that can fail answers a value, a negative errno or -1 or null, rather than exiting, because the language has no exceptions and a caller has to be able to turn the failure into its own diagnostic.

A wasm32 target has no processes and no host to ask, so the checker refuses spawn, spawnWithFds, kill, waitPid, availableParallelism, totalMemory, the scheduling calls, signalFd and readSignal there; a WASI build answers -1 from spawnSync, spawnSyncTo and spawnPiped. spawn, kill, waitPid and the scheduling calls write state outside the program, so a scope's task or a parallel body that calls one is refused as any shared write is.

A supervisor polls

A blocking waitPid(pid, 0) cannot be woken by SIGTERM once signalFd() is installed, so a supervisor that must answer a signal while its children run reaps with flag 1 (WNOHANG) on each tick of a pollWait loop that also watches the signal descriptor, and stops its children with kill when readSignal answers.

The rules: https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#directories-and-subprocesses, https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#the-environment, https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#the-clock, https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#the-host-the-wall-clock-entropy-file-times-and-signals, https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#children-and-the-machine-spawn-kill-waitpid-availableparallelism-totalmemory and https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#scheduling-setnice-setidlepriority-setcpuaffinity

Functions

availableParallelism

How many CPUs the program may use: the smallest of the CPUs online, the ones its thread may run on (an affinity mask, a container's cpuset), a cgroup v2 CPU quota rounded up, and NISH_NUM_THREADS when that is a positive number, which can lower the count and never raise it. It needs no --threads, and a task may call it.

const availableParallelism: () => i32
returnsi32

The count, at least 1.

exit

The global process.exit: a terminator, which never is how tsc spells it.

const exit: (code: i32) => never
codei32required

The exit status.

returnsnever

Never: the program ends.

getenv

The value of environment variable name as the call runs. The bytes are copied into the arena, so the result is an ordinary string that outlives any later change to the environment, and it is bytes: a value that is not valid UTF-8 comes back as those bytes. Two reads are two calls, never folded into one, because linked C may change the environment between them. There is no setenv.

const getenv: (name: string) => string | null
namestringrequired

The variable's name.

returnsstring | null

The value, a zero-length string for a variable set to nothing (CC=), or null when the variable is unset; narrow it with if (cc !== null).

kill

Send sig to pid. Only 0, 2 (SIGINT), 9 (SIGKILL) and 15 (SIGTERM) are taken, whose numbers are the same on Linux and Darwin, so a number means the same signal on every host. A positive pid may be any process of this user, not only a child.

const kill: (pid: i32, sig: i32) => i32
pidi32required

The process, above 0.

sigi32required

0, 2, 9 or 15.

returnsi32

0, or a negative errno: -22 for any other sig or a pid of 0 or below (which kill(2) reads as a process group or every process), -3 ESRCH when no process has the pid (a child already reaped included), -1 EPERM when it is another user's.

monotonicNanos

CLOCK_MONOTONIC in nanoseconds. The origin is arbitrary, so only the difference between two reads means anything: it is not comparable between two processes or two machines, and it is not a date. Two reads with work between them never fold into one.

const monotonicNanos: () => i64
returnsi64

The clock's reading.

readSignal

Block until SIGTERM or SIGINT arrives. It can wait forever.

const readSignal: (fd: i32) => i32
fdi32required

The descriptor signalFd() answered; an i32 in both number modes, and an f64, i64 or string is refused rather than converted.

returnsi32

15 or 2, or -1 for a descriptor that is not signalFd()'s and for a read that fails.

setCpuAffinity

Pin the calling process to the one CPU cpu with sched_setaffinity. Narrow-only: it never moves a process onto a CPU it was kept off. availableParallelism() answers 1 afterwards, and children started afterwards inherit the mask.

const setCpuAffinity: (cpu: i32) => i32
cpui32required

The CPU's index.

returnsi32

0; -22 with no change for a cpu below 0, at or past CPU_SETSIZE, or outside the CPUs the process may already run on; -95 on Darwin and under Node, which have no affinity call.

setIdlePriority

Move this process to SCHED_IDLE, which runs it only when nothing else wants the CPU. An unprivileged process can never leave it, and an idle process can starve on a saturated machine, so a caller keeps a normal-priority fallback (setNice(19), or a deadline) for work that must finish. Per thread, as setNice is.

const setIdlePriority: () => i32
returnsi32

0, a negative errno, or -95 on Darwin, which has no such policy.

setNice

Set the nice value with setpriority(PRIO_PROCESS, 0, n). Lower-only, even as root: the priority never rises. It sets the calling thread's value and every thread's started after it, so it belongs at the top of main; children started afterwards inherit it.

const setNice: (n: i32) => i32
ni32required

The nice value, 0..19.

returnsi32

0, or a negative errno: -22 EINVAL outside 0..19 and -13 EACCES below the current value, both with no system call.

signalFd

A descriptor that becomes readable when SIGTERM or SIGINT arrives: the read end of a pipe a sigaction handler writes one byte to per signal, so the signals' default action never runs, whichever thread a signal lands on. Installing the handler overrides a disposition the process started with, so a signal its parent ignored is heard. Made once.

const signalFd: () => i32
returnsi32

The same descriptor every call, or -1 when it cannot be made.

spawn

Start argv[0], searched on PATH, exactly as spawnSync does (the same vector, environment, streams and working directory), without waiting. The child is this process's until waitPid reaps it; one never reaped stays a zombie until the program exits, as in C. Test pid > 0 before handing the answer on: a failure such as -1 passed to waitPid reads as "any child".

const spawn: (argv: string[]) => i32
argvstring[]required

The program and its arguments.

returnsi32

The child's pid, or a negative errno: -22 EINVAL for an empty vector or an argument holding a NUL, posix_spawnp's own error otherwise, so a program that is not there is -2 ENOENT. Under --sandbox with a list of granted programs, a spawn that cannot be held to one program is refused: -11 (EAGAIN), -38 (ENOSYS), -10 (ECHILD) or the kernel's own error, with a line on stderr.

spawnPiped

The same run as spawnSync, with every stream a pipe: the child reads stdin's bytes and then end of file, and whatever it writes to its stdout and stderr is appended to stdout and stderr, which keep what they held. It is the run for a child that takes a secret on stdin, which ps and /proc do not show. A child that exits without reading its stdin is not a failure.

The child inherits the environment and working directory, and no descriptor of the program but its three streams; it starts with SIGPIPE as the program had it, and the program's own SIGPIPE from writing to a child that stopped reading is absorbed. One poll loop writes and drains, so a child that fills one pipe cannot deadlock the parent.

const spawnPiped: (
  argv: string[],
  stdin: readonly u8[],
  stdout: u8[],
  stderr: u8[],
) => i32
argvstring[]required

The program and its arguments.

stdinreadonly u8[]required

The bytes the child reads.

stdoutu8[]required

Grows by the child's stdout; neither readonly nor a typed array, since the runtime pushes onto it.

stderru8[]required

Grows by the child's stderr, under the same rule.

returnsi32

The status or 128 + n as spawnSync answers; -1 for an empty vector, a child that cannot be started, a pipe or poll that fails, and a WASI build; -2 when a stream passes 16 MiB (NISH_PIPED_CAP), which kills the child with SIGKILL and leaves that array holding the first 16 MiB.

spawnPipedWithin

spawnPiped with a deadline: the same captured run, killed with SIGKILL and reaped once timeoutMs milliseconds have passed since it started, and a negative timeoutMs is no deadline, so -1 makes it spawnPiped. The deadline covers the whole run, the wait for the child's exit included, on the monotonic clock. Only the child's pid is killed, never a grandchild, and a grandchild that keeps an output pipe open makes the run wait for it until the deadline.

const spawnPipedWithin: (
  argv: string[],
  stdin: readonly u8[],
  stdout: u8[],
  stderr: u8[],
  timeoutMs: i32,
) => i32
argvstring[]required

The program and its arguments.

stdinreadonly u8[]required

The bytes the child reads.

stdoutu8[]required

Grows by the child's stdout, the bytes read before a kill included; neither readonly nor a typed array.

stderru8[]required

Grows by the child's stderr, under the same rule.

timeoutMsi32required

The milliseconds the run may take; negative for none.

returnsi32

spawnPiped's answer (the status or 128 + n, -1, or -2 for a stream past 16 MiB), or -3 when the deadline passed and the child was killed.

spawnSync

Run argv[0], searched on PATH, with argv as its argument vector, and wait for it. The child inherits this process's environment, streams and working directory. The runtime keeps each element's bytes pointer for the child, so the array escapes; an embedded NUL truncates an argument.

const spawnSync: (argv: string[]) => number
argvstring[]required

The program and its arguments.

returnsnumber

The child's exit status, 128 + n when signal n killed it, or -1 when the vector is empty, when the child cannot be started or waited for, and always on WASI.

spawnSyncTo

The same run as spawnSync, with each stream sent to a file rather than inherited. Each path is created or truncated at 0644, as writeFileSync does, and an empty path leaves that stream inherited, so one call can capture stdout and let stderr through. The two paths must not name one file: each is opened separately, with its own offset, so the streams would overwrite rather than interleave.

const spawnSyncTo: (
  argv: string[],
  stdoutPath: string,
  stderrPath: string,
) => number
argvstring[]required

The program and its arguments.

stdoutPathstringrequired

The file for the child's stdout, or "" to inherit it.

stderrPathstringrequired

The file for the child's stderr, or "" to inherit it.

returnsnumber

Every answer spawnSync gives, and -1 when a symbolic link is the last component of either path.

spawnWithFds

spawn, with the child holding fds[i] as descriptor 3 + i, close-on-exec cleared there. Its streams 0 to 2 are this process's, and no other descriptor of this process reaches it but one opened without close-on-exec, which nothing the runtime opens is. Any order works: fds may list a descriptor that is already its own target ([3]), another entry's target ([4, 3]), or the same one twice. The child shares each descriptor's open file, its offset and its status flags, O_NONBLOCK among them, and this process keeps its own. Reap the pid with waitPid.

const spawnWithFds: (
  argv: string[],
  fds: readonly i32[],
) => i32
argvstring[]required

The program and its arguments.

fdsreadonly i32[]required

The descriptors the child receives from 3 onward; an empty array is spawn exactly.

returnsi32

The child's pid, or a negative errno: -22 for more than 64 descriptors or a negative one (before anything is opened or started), -9 for one that is not open, -24 (or -22 above the descriptor limit) for a scratch descriptor the system cannot give, and spawn's errors.

totalMemory

The machine's physical memory: _SC_PHYS_PAGES times the page size on Linux, hw.memsize on Darwin. The machine's, not a cgroup's limit. A task may call it.

const totalMemory: () => i64
returnsi64

The bytes, or -1 where the host does not say.

waitPid

Reap a child. The status is spawnSync's: the exit code, or 128 + n when signal n ended it. An array because the language has no tuple.

const waitPid: (pid: i32, flags: i32) => i32[]
pidi32required

A child's pid, or -1 for any child.

flagsi32required

0 to block, or 1 for WNOHANG.

returnsi32[]

A fresh [pid, status]; [0, 0] for a WNOHANG wait with a child left and none exited; [-10, 0] ECHILD with no child to wait for, [-4, 0] EINTR when a signal interrupted the wait (after signalFd() a blocking wait restarts and never sees it), [-22, 0] for any other flag bit or a pid that is neither -1 nor positive.

wallClockNanos

CLOCK_REALTIME in nanoseconds since 1970-01-01 UTC: Date.now's clock at a nanosecond's grain. It steps, and can go backwards, when the system time is set, so a duration is monotonicNanos's job. Not refused on wasm.

const wallClockNanos: () => i64
returnsi64

The timestamp.

Constants

arch

arch: string

The architecture: "x64", "arm64", or "unknown".

argv

argv: readonly string[]

The command line; argv[0] is the program path, as in C. Read-only.

platform

platform: string

The operating system the program runs on: "linux", "darwin", or "unknown".