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")
end0 argumentsSystem.exit #
System.exit(code: Int) -> VoidEnds the program at once, with an exit code.
def main() -> Void
puts("before")
System.exit(3)
puts("never printed")
endbeforeSystem.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?)
endvi
falseThe VM hides the variables it keeps for itself:
AGENTICA_CHANNEL, andUV_USE_IO_URINGwhen the VM set it. A program started withProcess.spawndoes not get them either.AGENTICA_VM_METRICSandAGENTICA_VM_METRICS_FILEare reserved for the VM metrics. A program started withProcess.spawndoes not get them, butSystem.envstill shows them to your program.
System.os #
System.os() -> StringThe operating system of the running program. It needs no flag.
"linux","macos"or"windows".- On any other system, the lowercase name that
unamegives. "unknown"when the system cannot say, or when the name is not printable ASCII.
def main() -> Void
puts(System.os().length > 0)
endtrueSystem.pid #
System.pid() -> IntThe 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)
endtrueSystem.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
Termboth 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
recvreturnschannel: 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.
sendon the channel, or on its address, returnserror("signal: channel is read only")with kindargument.QuitorKillin the list stops the run withRUNTIME-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 toTermandInt, unless the program started withQuitignored (a job that a shell runs in the background).Killcannot be caught.- An empty list returns
error("signal: no signals")with kindargument. A signal that the program started with ignored (nohup;IntandQuitfor 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 returnserror("signal: ignored when the program started")with kindsystem.signal. On Windows every call returnserror("signal: not supported on this system")with kindsystem.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,SIGCHLDand the signals of the VM’s garbage collector have noSystem.Signalvalue, so a program cannot take them. A program started withProcess.spawnstarts 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
endchannel: timed outSystem.signal_number #
System.signal_number(signal: System.Signal) -> IntThe 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))
end15System.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 emptycommor one over 15 bytes returnserror("signal: comm must be 1 to 15 bytes without NUL"), both with kindargument. - Another name returns
error("signal: the process has another name")with kindsystem.signal, and the process gets nothing. A process that has ended, or one of another user, returns an error that starts withsignal: cannot signal the process, with kindprocess.failedand the system’s error number as its code. --deny-runturns it off: it returnserror("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 kindsystem.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
endStd.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?)
endtrue
falseFrontEnd #
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() -> IntWall-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)
endtrueTime.monotonic_ms #
Time.monotonic_ms() -> IntMilliseconds 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)
endtrueTime.monotonic_ns #
Time.monotonic_ns() -> IntNanoseconds 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)
endtrueRandom.int #
Random.int(min: Int, max: Int) -> IntA 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)
endtrueRandom.float #
Random.float() -> FloatA 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)
endtrueRandom.seed #
Random.seed() -> IntThe 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)
endtrueEach 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
Randomfor secrets: it is seeded, and--seedrepeats it. Use OpenSSL.Random for keys, tokens and IDs.