Environment

The environment is your program's practical link to the outside world. Most programs meet it first as the env argument passed to the root actor.

The root actor receives the builtin environment actor Env as its env parameter. Env is the runtime-provided handle for outside-world access.

actor main(env):
    print("args:", env.argv)
    env.exit(0)

You can think of env as the handle your program receives for talking to the world around it. It is passed into main; it is not a hidden global that every function can reach automatically. If a helper only needs one small piece of that power, pass the smaller piece instead of the whole environment.

Env provides, among other things:

env.argv for command-line arguments
env.cap for the root WorldCap capability
env.vars for environment variables
env.stdio for stdin, stdout, stderr and terminal settings
env.process for starting child processes
env.exit(n) to terminate the program
Environment variables
Reading stdin input
Interactive stdin input
Child processes

env.vars, env.stdio and env.process are actors. A call to one of them works like any other actor call: a call whose result is not used does not wait for the actor to run it, and the calls that one actor makes to the same service run in the order they were made. See Async method calls.

env.stdio.out(s) and env.stdio.err(s) write the str s to stdout and stderr. env.stdio.outb(b) and env.stdio.errb(b) write the bytes b unchanged, so binary data and output that is not valid UTF-8 reach stdout and stderr as they are.

Env also has methods that call these services, such as env.getenv, env.setenv, env.stdout_write and env.stdin_install. Existing programs use them. New code should call env.vars, env.stdio and env.process directly.

Use env when code needs process arguments, environment variables, standard input, terminal configuration or child processes. Pass it only to the code that actually needs that access. When a helper needs only one of the services, pass it that service, such as env.vars, instead of the whole env.

env is best understood as a bundle of process-level capabilities, not as one ordinary argument. It carries authority over things such as arguments, environment variables, standard input, terminal configuration and child processes. If that whole bundle gets threaded through many layers, those layers quietly become coupled to process concerns even when they only need one small part of it.

In larger programs, treat the root actor as the place where broad authority is received, then pass inward only the narrower capability or value a helper actually needs. That keeps APIs honest about what they depend on, makes tests easier to fake, and prevents a small utility from accidentally gaining much wider access to the outside world than its job requires.

Keyboard shortcuts

Acton Guide

Environment