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)

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. To be sure the output is written before the program exits, wait for the call, as in await async env.stdio.out(s), before env.exit(n).

Use a plain env.exit(n) to request shutdown with status n. Like other actor calls used as statements, it is asynchronous: code after it can run before shutdown starts. Put success work in an else branch after an error exit, or return from a helper after requesting exit.

Exit does not wait for other actors to finish their work. Await the output, cleanup or other operation that must finish before requesting exit; awaiting env.exit(n) itself does not provide that ordering.

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.