System, Time and Random

System.args #

System.args() -> List[String]

Gives the words after the file name: agentica tool.agc a b gives ["a", "b"].

def main() -> Void
  args = System.args()
  puts("#{args.size} arguments")
end
Output
0 arguments

System.exit #

System.exit(code: Int) -> Void

Ends the program at once, with an exit code.

def main() -> Void
  puts("before")
  System.exit(3)
  puts("never printed")
end
Output
before

System.env #

System.env(name: String) -> Result[String]

Reads an environment variable of the program. With --deny-env (or --sandbox) it returns an error that begins with denied: --deny-env. There is no call that lists all variables.

  • A variable that is not set is an error. A variable set to the empty string is ok("").
  • A name that is empty, or has = or a NUL in it, is an error.
  • A value that is not valid UTF-8 is not an error. Each byte that is not part of a valid UTF-8 sequence becomes U+FFFD.
  • The home directory is System.env("HOME").
def main() -> Void
  editor = System.env("AGENTICA_EXAMPLE_NOT_SET").unwrap_or("vi")
  puts(editor)
  puts(System.env("A=B").ok?)
end
Output
vi
false

The VM hides the variables it keeps for itself:

  • AGENTICA_CHANNEL, and UV_USE_IO_URING when the VM set it. A program started with Process.spawn does not get them either.
  • AGENTICA_VM_METRICS and AGENTICA_VM_METRICS_FILE are reserved for the VM metrics. A program started with Process.spawn does not get them, but System.env still shows them to your program.

System.os #

System.os() -> String

The operating system of the running program. It needs no flag.

  • "linux", "macos" or "windows".
  • On any other system, the lowercase name that uname gives.
  • "unknown" when the system cannot say, or when the name is not printable ASCII.
def main() -> Void
  puts(System.os().length > 0)
end
Output
true

System.pid #

System.pid() -> Int

The process id of the running program. It needs no flag. Pass it to --driver-pid when you start a VM. That VM then checks that its parent is this program.

def main() -> Void
  puts(System.pid() > 0)
end
Output
true

System.subscribe #

System.subscribe(signals: List[System.Signal]) -> Result[Channel[System.Signal]]

Receives the listed operating system signals as values on a new channel, instead of letting them stop the program. System.Signal is an enum: Term, Int (Ctrl-C), Hup, Usr1, Usr2, Quit and Kill; the first five can be subscribed to. A program that must clean up on Ctrl-C or on a container stop receives the first value, cleans up, and exits with 128 + System.signal_number(signal), the code a shell expects.

  • The channel holds one pending value per signal: a value is queued only when that signal has none waiting, so a burst of one signal gives one value and the signal never waits for the program. The channel does not count how many times a signal came.
  • Each subscription gets every signal it lists, so two tasks that subscribe to Term both get it. A signal listed twice counts once.
  • The calling task owns the channel, like a handle. When that task ends, in any way, or the channel is closed, the subscription ends: the values still queued can be received, then recv returns channel: closed. When the last subscription to a signal ends, that signal stops the program again.
  • A signal that comes before the subscription stops the program, as it does without one. While a subscription is open the run waits for its signals, so a program whose tasks all wait for one does not end.
  • send on the channel, or on its address, returns error("signal: channel is read only") with kind argument.
  • Quit or Kill in the list stops the run with RUNTIME-INVALID-SIGNAL. Quit (Ctrl-\) is the force stop: it stops the child programs, writes the files and exits with 131, also in a program that subscribed to Term and Int, unless the program started with Quit ignored (a job that a shell runs in the background). Kill cannot be caught.
  • An empty list returns error("signal: no signals") with kind argument. A signal that the program started with ignored (nohup; Int and Quit for a job that a shell runs in the background) stays ignored and the other listed signals are subscribed; when every listed signal was ignored, the call returns error("signal: ignored when the program started") with kind system.signal. On Windows every call returns error("signal: not supported on this system") with kind system.signal, and Ctrl-C and Ctrl-Break stop the program.
  • It needs no flag, also under --sandbox: it only changes what the program does with its own signals.
  • SIGPIPE, SIGCHLD and the signals of the VM’s garbage collector have no System.Signal value, so a program cannot take them. A program started with Process.spawn starts with the default action for every signal.
def main() -> Void
  signals = System.subscribe([System.Signal.Term]).unwrap!
  case signals.recv(100)
    ok(signal) -> System.exit(128 + System.signal_number(signal))
    error(e) -> puts(e.message)
  end
end
Output
channel: timed out

System.signal_number #

System.signal_number(signal: System.Signal) -> Int

The number of the signal: Term is 15, Int 2, Hup 1, Quit 3 and Kill 9. Usr1 and Usr2 are 10 and 12 on Linux and Windows, 30 and 31 on macOS. A process that a signal ended has the exit code 128 + that number.

def main() -> Void
  puts(System.signal_number(System.Signal.Term))
end
Output
15

System.signal #

System.signal(pid: Int, signal: System.Signal, comm: String) -> Result[Void]

Sends a signal to a process that is not your program’s child, such as a program that a child started. comm is the process’s name as Linux keeps it in /proc/<pid>/comm: the file name of the program, cut to 15 bytes (Runner.Listener). The signal goes only to the process that has that pid and that name when the call runs: the VM holds the process with a pidfd while it compares the name, and signals through it, so a process that took a reused pid is never reached. For your program’s own children use Process.signal.

  • A pid of 0 or less, or your program’s own, returns error("signal: pid must be above 0 and not the program's own"), and an empty comm or one over 15 bytes returns error("signal: comm must be 1 to 15 bytes without NUL"), both with kind argument.
  • Another name returns error("signal: the process has another name") with kind system.signal, and the process gets nothing. A process that has ended, or one of another user, returns an error that starts with signal: cannot signal the process, with kind process.failed and the system’s error number as its code.
  • --deny-run turns it off: it returns error("denied: --deny-run turns off signalling processes").
  • It needs Linux 5.3 or later. On an older kernel, under a seccomp filter that refuses pidfds, and on macOS and Windows it returns error("signal: pidfd is unavailable") with kind system.signal.
def main() -> Void
  pid = System.args()[0].to_i!
  case System.signal(pid, System.Signal.Term, "Runner.Listener")
    ok(_) -> puts("sent")
    error(e) -> puts(e.message)
  end
end

Std.source #

Std.source(path: String) -> Result[String]

The text of a std/ source that the agentica binary carries, by its exact path in stdlib/: "queue.agc", "bdd/gherkin.agc", "prelude/list.agc"; "internal/compiler/..." is the private core of the front end that std/analysis uses. Any other path is an error, "std/queue.agc" and "queue" included. It needs no flag and reads only data of the binary, so tasks may call it at the same time. A doc or lint tool can read the std sources of the binary that runs it this way.

def main() -> Void
  text = Std.source("queue.agc").unwrap_or("")
  puts(text.start_with?("## "))
  puts(Std.source("nope.agc").ok?)
end
Output
true
false

FrontEnd #

FrontEnd.hand_off(program, options, arguments), FrontEnd.std_source(path) and FrontEnd.stdin_bytes() belong to the front end of the agentica binary. That binary compiles a program and hands it to the VM: hand_off takes the compiled program (a Bytes) and runs it in a new runtime with the given VM options and arguments, std_source reads an embedded std/ source by its path in stdlib/, and stdin_bytes reads standard input to its end as a Result[Bytes] (an error over 16 MiB or when the read fails; a later call reads on from there). They are not for your programs: a program that calls them, and any front end run by agentica run, stops with RUNTIME-FRONT-END-ONLY. They need no flag.

Time.now_ms #

Time.now_ms() -> Int

Wall-clock time in milliseconds since 1970. It can jump when the system clock changes. &Time.now_ms is the clock as a value (Fn[Int]), to pass to code that a test gives a fixed clock.

def main() -> Void
  puts(Time.now_ms() > 1700000000000)
end
Output
true

Time.monotonic_ms #

Time.monotonic_ms() -> Int

Milliseconds from an unknown start. The value never goes back. Use it to measure how long something takes. On a Linux host where reading the exact clock is a system call (such as an HPET clock source) it comes from the kernel’s coarse clock, which is cheap to read and lags the exact time by up to about two kernel ticks (at most about 20 ms), but it is never behind an earlier Time.monotonic_ns or a Task.sleep that ended: after Task.sleep(ms) it has gone on by at least ms. Use Time.monotonic_ns for spans of a few milliseconds.

def main() -> Void
  start = Time.monotonic_ms()
  Task.sleep(5)
  elapsed = Time.monotonic_ms() - start
  puts(elapsed >= 5)
end
Output
true

Time.monotonic_ns #

Time.monotonic_ns() -> Int

Nanoseconds from the same clock and the same unknown start as Time.monotonic_ms. They never go back. Use it for work too short for milliseconds. An Int holds about 292 years of nanoseconds, so the value does not overflow in practice.

def main() -> Void
  start = Time.monotonic_ns()
  Task.sleep(5)
  elapsed = Time.monotonic_ns() - start
  puts(elapsed >= 4000000)
end
Output
true

Random.int #

Random.int(min: Int, max: Int) -> Int

A random Int from min to max, uniform. Both are included. min > max stops the program with RUNTIME-INVALID-RANGE.

def main() -> Void
  roll = Random.int(1, 6)
  puts(roll >= 1 and roll <= 6)
end
Output
true

Random.float #

Random.float() -> Float

A random Float from 0.0 up to, but not including, 1.0.

def main() -> Void
  x = Random.float()
  puts(x >= 0.0 and x < 1.0)
end
Output
true

Random.seed #

Random.seed() -> Int

The seed of the run, from 0 to 2147483647: the N of --seed N, or the one drawn from the operating system when there is no --seed. Every task gives the same number. Print it when something fails, then run again with --seed and that number to get the same random numbers.

def main() -> Void
  seed = Random.seed
  puts(seed >= 0 and seed <= 2147483647)
end
Output
true

Each run gives other numbers. Run with agentica --seed 42 file.agc to get the same numbers every time (N is 0 .. 2147483647, otherwise the exit status is 2). Without --seed, the generator is seeded from the operating system.

  • Each task has its own generator. It is split from its parent when the task is spawned, so each task repeats its own numbers: the main task starts from the seed, and each spawn takes one draw from its parent. Timers, I/O and more than one scheduler can still change how tasks interleave, so a run of several tasks as a whole is not repeatable.
  • Do not use Random for secrets: it is seeded, and --seed repeats it. Use OpenSSL.Random for keys, tokens and IDs.