process Process Management

process is Alia's standard library process management module, providing process-related operations such as environment variable access and command execution.

Importing the Module

import 'process' as process ~ import as a variable
import 'process' ~ import into scope

Process Information Properties

The following properties can be read directly, without being called:

pid

pid is the PID of the current process, of type Number.

const pid = process.pid
print pid

ppid

ppid is the PID of the parent process, of type Number.

const ppid = process.ppid
print ppid

platform

platform is the operating system platform, of type String. Possible values: 'linux', 'darwin', 'win32'.

print process.platform

arch

arch is the CPU architecture, of type String. Possible values: 'x64', 'arm64', 'ia32'.

print process.arch

version

version is the version number of the Alia runtime, of type String.

print process.version

title

title is the process title, readable and writable.

print process.title
process.title = 'my-app'

Working Directory

cwd

cwd returns the current working directory as a String.

const dir = process.cwd
print dir

chdir

chdir changes the current working directory.

process.chdir '/tmp'

Process Runtime Information

uptime

uptime is the amount of time the process has been running (in seconds), of type Number.

const up = process.uptime
print up

memory

memory returns the process memory usage as an Object with the following properties:

Property	Type	Description
rss	Number	Resident set size (bytes)
heapTotal	Number	Total V8 heap size (bytes)
heapUsed	Number	Used V8 heap size (bytes)
external	Number	V8 external memory (bytes)

const mem = process.memory
print mem.rss
print mem.heapUsed

Environment Variables

envGet

envGet reads an environment variable and returns a String; returns Null if the variable does not exist.

const home = process.envGet 'HOME'
print home

if (Ok home) {
  print 'Home: ' .. home
}

envSet

envSet sets an environment variable.

process.envSet 'MY_VAR' to 'hello'

envHas

envHas checks whether an environment variable exists and returns a Boolean.

if process.envHas 'PATH' {
  print 'PATH exists'
}

envDelete

envDelete deletes an environment variable.

process.envDelete 'MY_VAR'

envAll

envAll returns all environment variables as an Object.

const allEnv = process.envAll
const keys = Object.keys allEnv
print keys.length

Process Control

exit

exit terminates the current process with the exit status code code.

process.exit 0   ~ normal exit
process.exit 1   ~ abnormal exit

kill

kill sends a signal to the process with the given PID; signal defaults to 'SIGTERM'. It throws when the signal cannot be delivered (no such process, insufficient permission, or signalling unsupported on the current platform).

process.kill 12345               ~ default SIGTERM
process.kill 12345 with 'SIGKILL'

Command Execution

exec

exec executes a command through the shell and returns an Object; it does not throw an error when the command fails, instead writing the error information into the returned result.

The optional parameter options (Object) supports: cwd (working directory), env (environment variable object), timeout (timeout in milliseconds), and input (standard input).

The returned object contains the following properties:

Property	Type	Description
stdout	String	Standard output
stderr	String	Standard error
code	Number	Exit code

const result = process.exec 'echo Hello, Alia!'
print result.code     ~ 0
print result.stdout   ~ "Hello, Alia!\n"

~ Execute in a specified working directory
const inTmp = process.exec 'pwd' with *[cwd: '/tmp']

~ No error is thrown when the command fails
const fail = process.exec 'exit 42'
print fail.code   ~ 42

spawn

spawn executes a command directly without going through the shell and returns an Object; it is safer than exec (no risk of shell injection) and provides access to the child process PID.

The optional parameter options (Object) supports: cwd (working directory), env (environment variable object), timeout (timeout in milliseconds), input (standard input), and stdio (standard stream mode: 'pipe' captures output into the returned object, the default; 'inherit' passes it through to the current terminal; 'ignore' discards it. When inherit/ignore is specified, the returned object's stdout/stderr are empty strings).

The returned object contains the following properties:

Property	Type	Description
stdout	String	Standard output
stderr	String	Standard error
code	Number	Exit code
pid	Number	Child process PID
signal	String?	Termination signal (if any)

const result = process.spawn 'ls' with ['-la', '/tmp']
print result.code
print result.pid
print result.stdout

~ Execute in a specified working directory
const inTmp = process.spawn 'pwd' with [] with *[cwd: '/tmp']

~ Output passes through to the current terminal (recommended for long-running compile/run tasks)
process.spawn 'cargo' with ['build'] with *[cwd: '.', stdio: 'inherit']

Example Code

import 'process' as process

~ Basic process information
print 'PID: ' .. process.pid
print 'Platform: ' .. process.platform
print 'Architecture: ' .. process.arch

~ Working directory
const dir = process.cwd
print 'Current directory: ' .. dir

~ Environment variables
const shell = process.envGet 'SHELL'
if (Ok shell) {
  print 'Shell: ' .. shell
}

if !(process.envHas 'ALIA_TEST_VAR') {
  process.envSet 'ALIA_TEST_VAR' to 'hello'
}

const allEnv = process.envAll
print 'Total environment variables: ' .. (Object.keys allEnv).length

process.envDelete 'ALIA_TEST_VAR'

~ Execute commands
const echo = process.exec 'echo Hello from Alia'
print echo.stdout

const list = process.spawn 'ls' with ['-la', '/tmp']
print 'ls exit code: ' .. list.code
print 'Child process PID: ' .. list.pid

~ Process uptime
print 'Uptime: ' .. process.uptime .. ' seconds'

~ Memory usage
const mem = process.memory
print 'Heap memory: ' .. mem.heapUsed .. ' / ' .. mem.heapTotal .. ' bytes'

Next Steps

• args Command-Line Interaction