Reference

std/os/process

std/os/src/process.trb

CurrentProcess - what the operating system knows about this process: its identifier and its parent's, the executable it runs, its working directory, how long it has been running, and the resources it uses and may use (ProcessResources, its processors, its memory limit). What the process does - its arguments, exit, the children it starts - is std/process.

The identifiers and the resources are a match OperatingSystem.current whose arm hands the question to the directory of that system; the executable, the working directory and the uptime are one native each that every system answers through the runtime's platform layer.

type CurrentProcess

native type CurrentProcess

What the operating system knows about this process. What the process does - arguments, exit, children - is std/process.

Examples

match CurrentProcess.executable() {
  Ok(path) => print "running {path}"
  Fail(error) => print error
}
print "process {CurrentProcess.identifier()}, up for {CurrentProcess.uptime()}"
const used = CurrentProcess.resources()?
print "{used.resident} resident, at most {used.peakResident}"

Pitfalls

  • There is no setWorkingDirectory: the working directory is shared by every task of the process, and a relative path one task resolves would change its meaning under another. A child is given a working directory when it is started instead.
  • Inside torb run the program is interpreted by torb: CurrentProcess.executable answers the entry file, which is what executes (a program with Resource literals is staged in the toolchain's cache and answers that name, so its resources are beside it), and the identifiers, the uptime and the resources are those of the torb process.

Related

  • Process of std/process - the arguments, exit and the children of this process.
  • File.absolutePath of std/fs - a path made absolute against the same working directory.

fn identifier

static fn identifier(): Int

The identifier the system gave this process: the process id of every system's tools.

fn parentIdentifier

static fn parentIdentifier(): Result<Int, OsError>

The identifier of the process that started this one.

Errors

  • OsError.Missing where the parent is not known: on Linux a parent outside the process's namespace (a container's first process), on Windows a parent that is gone from the list of processes.
  • OsError.Unsupported in the browser, where a page is no process of the machine.

fn executable

static fn executable(): Result<Path, OsError>

The absolute path of the running executable, with every symbolic link resolved where the system resolves them: /proc/self/exe on Linux, _NSGetExecutablePath and realpath on macOS, GetModuleFileNameW on Windows, the sysctl KERN_PROC_PATHNAME on FreeBSD. Inside torb run it is the entry file of the program.

Errors

  • OsError.Unsupported where the system keeps the path nowhere a program can read (the browser).

fn workingDirectory

static fn workingDirectory(): Result<Path, OsError>

The directory a relative path is resolved against: always what File.absolutePath(".") answers, because both read it through the same function of the runtime. Inside a sandbox it is the base the sandbox resolves against.

Errors

  • OsError.Failed where the directory cannot be read, such as a working directory that was removed.

fn uptime

static fn uptime(): Duration

How long this process has been running, on the monotonic clock: the runtime reads it before main starts. In whole milliseconds, rounded up, so a process that has run at all answers more than zero.

fn resources

static fn resources(): Result<ProcessResources, OsError>

What this process has used so far: its processor time in user and in system mode, and its resident memory now and at its peak.

Errors

  • OsError.Unsupported on FreeBSD, whose slice has not come yet, and in the browser, where a page is no process.
  • OsError.Malformed where /proc/self/status of Linux has no VmRSS line.
  • OsError.Failed where the system's call fails, with its words.

fn processors

static fn processors(): Result<Int, OsError>

How many processors this process may keep busy at once - the number to size a pool of workers by. Not the machine's: the processors it may run on (its affinity, which taskset, start /affinity and a container's cpuset narrow), and fewer where it may only use part of their time - a cgroup's CPU quota on Linux (--cpus of a container), a job object's CPU rate on Windows - rounded up. macOS answers hw.ncpu. Never less than one.

Errors

  • OsError.Unsupported on FreeBSD, whose slice has not come yet, and in the browser.
  • OsError.Malformed where a cgroup's cpu.max or cpu.cfs_quota_us is not a quota.

fn memoryLimit

static fn memoryLimit(): Result<ByteSize?, OsError>

The most memory this process may hold before the system stops it, or None where nothing limits it but the machine: the lowest memory.max (cgroup version 2) or memory.limit_in_bytes (version 1) of the cgroups it is in on Linux, and the memory limit of its job object on Windows - which a dev binary of torb sets itself. macOS has no such limit and answers None.

A cgroup file that is not there, or a /sys this process may not read - a container that hides it - is no limit, so that case answers Ok(None) rather than an error.

Errors

  • OsError.Unsupported on FreeBSD, whose slice has not come yet, and in the browser.
  • OsError.Malformed where a cgroup's limit is no number.

type ProcessResources

type ProcessResources with Show, Equals

What the current process has used, from CurrentProcess.resources: getrusage on Linux and macOS with the resident size each reads its own way, GetProcessTimes and GetProcessMemoryInfo on Windows.

field userTime

userTime: Duration

The processor time spent running this process's own code, in whole milliseconds.

field systemTime

systemTime: Duration

The processor time the kernel spent for this process - its system calls, its page faults - in milliseconds.

field resident

resident: ByteSize

The memory of this process that is in physical memory now: the resident set, the working set on Windows.

field peakResident

peakResident: ByteSize

The most ProcessResources.resident has been since the process started; never less than it.