std/sys/sysinfo
std/sysinfo — read-only host introspection, in pure Axle.
Every fn is best-effort: if the host can't answer (e.g. no
hostname configured), the result is a sensible default
("" / 0) rather than an exception. Code that needs a
strict guarantee should validate the value at the call site.
The two queries whose OS API diverges — how many processors are
online, and what the machine calls itself — are @target-selected
declarations rather than one body branching at run time: the Windows
arm calls an entry point no unix has and vice versa, so neither could
typecheck against the other's world. Each binds the symbol it needs
beside the one function that calls it, because a @target-gated
declaration cannot be re-exported through a target-agnostic use.
Cost: nothing here is cached, so every call is the syscall behind it.
That is deliberate for hostname — a machine can be renamed under a
long-lived program — and cheap enough for the rest, which a program
reads at startup. Code that polls one of these in a loop should hold
the answer itself.
Free functions
| Type | Method and description |
|---|---|
| __activeProcessorCount(group : i32) : i32 GetActiveProcessorCount — the count across every processorgroup. Asking for the caller's own group instead would, on a machine with more than 64 logical processors, report one slice of it as the whole. |
| cpuCount() : i32 Number of hardware threads available; never below 1. |
| __sysconf(name : i32) : i64 sysconf — the one spelling every unix agrees on for a system limit.A negative or zero answer means the limit is indeterminate, which is the platform declining rather than a machine with no processors. |
| __scProcessorsOnline() : i32 _SC_NPROCESSORS_ONLN. The name is POSIX, the number is not: eachkernel assigns its own, so it is a per-target value rather than a shared constant. |
| __scProcessorsOnline() : i32 _SC_NPROCESSORS_ONLN, as Darwin numbers it. |
| cpuCount() : i32 Number of hardware threads available; never below 1.The processors the OS reports online, deliberately not narrowed by the process's affinity mask or its cgroup quota. The direction that runs is over-reporting inside a container or under taskset, so apool sized from it holds more workers than there are cores — a scheduling cost, never a correctness one. Under-reporting would leave hardware idle with nothing to say so. |
| pageSize() : i64 OS memory page size in bytes. The conventional 4 KiB, and a constant rather than a query. sysconf isbound above and would answer on unix, but its _SC_PAGESIZE number isassigned per kernel the way _SC_NPROCESSORS_ONLN is — so wiring it meansone verified constant per target, and a wrong one does not fail: it reads some other limit and returns a plausible number. Windows needs GetSystemInfo, whose answer arrives in a C-layout struct this languagecannot describe. A program aligning an mmap on this must query the platform itself; 4 KiB is the right answer on every target this compiler emits for, and the wrong one on a kernel configured for large pages. |
| __gethostname(buf : ptr, cap : i64) : i32 gethostname — the host's own name, as the kernel holds it.POSIX leaves it unspecified whether a truncated name is NUL-terminated, so the call is given one byte less than the buffer holds and the scan below stops inside it either way. |
| hostname() : string Host name; "" if unknown.Asked of the kernel rather than read from $HOSTNAME, which mostshells never export — an environment lookup answered "" on themajority of unix hosts and agreed with the kernel only by accident. |
| hostname() : string Host name; "" if unknown.%COMPUTERNAME% rather than a GetComputerNameEx call: the narrowform of that entry point renders the name through the process ANSI code page, and the wide form returns UTF-16, which Axle cannot marshal. The environment block is the same name, already UTF-8 by the time the runtime's env shim hands it over. |
| exePath() : string Absolute path to the running executable; "" on failure.Non-throwing — use std/env::currentExe for the throwing form, whichis the surface that keeps the refusals apart. Here they all collapse: this one returns a path and has no error to carry a reason in. |
| username() : string Best-effort current user name. Reads the conventional login environment variables in turn — $USER, then $LOGNAME (set byUnix login shells), then $USERNAME (Windows) — so the lookupsurvives shells and containers that populate only one of them. Returns "" when none is set (a daemon or bare container with nologin session). Pure Axle: no syscall, just the inherited env. |
| totalMemory() : i64 Total physical RAM in bytes. Not wired — there is no one syscall the three targets share — so it raises UnsupportedOperationExceptionrather than silently returning 0, which a caller would divide by. |
| availableMemory() : i64 Free (currently available) physical RAM in bytes. Not wired, for the same reason as totalMemory: raises UnsupportedOperationExceptionrather than returning 0. |
Method detail
#__activeProcessorCount
GetActiveProcessorCount — the count across every processor
group. Asking for the caller's own group instead would, on a machine
with more than 64 logical processors, report one slice of it as the
whole.
#cpuCount
Number of hardware threads available; never below 1.
#__sysconf
sysconf — the one spelling every unix agrees on for a system limit.
A negative or zero answer means the limit is indeterminate, which is
the platform declining rather than a machine with no processors.
#__scProcessorsOnline
_SC_NPROCESSORS_ONLN. The name is POSIX, the number is not: each
kernel assigns its own, so it is a per-target value rather than a
shared constant.
#__scProcessorsOnline
_SC_NPROCESSORS_ONLN, as Darwin numbers it.
#cpuCount
Number of hardware threads available; never below 1.
The processors the OS reports online, deliberately not narrowed by
the process's affinity mask or its cgroup quota. The direction that
runs is over-reporting inside a container or under taskset, so a
pool sized from it holds more workers than there are cores — a
scheduling cost, never a correctness one. Under-reporting would leave
hardware idle with nothing to say so.
#pageSize
OS memory page size in bytes.
The conventional 4 KiB, and a constant rather than a query. sysconf is
bound above and would answer on unix, but its _SC_PAGESIZE number is
assigned per kernel the way _SC_NPROCESSORS_ONLN is — so wiring it means
one verified constant per target, and a wrong one does not fail: it reads
some other limit and returns a plausible number. Windows needsGetSystemInfo, whose answer arrives in a C-layout struct this language
cannot describe.
A program aligning an mmap on this must query the platform itself; 4 KiB is
the right answer on every target this compiler emits for, and the wrong one
on a kernel configured for large pages.
#__gethostname
gethostname — the host's own name, as the kernel holds it.
POSIX leaves it unspecified whether a truncated name is
NUL-terminated, so the call is given one byte less than the buffer
holds and the scan below stops inside it either way.
#hostname
Host name; "" if unknown.
Asked of the kernel rather than read from $HOSTNAME, which most
shells never export — an environment lookup answered "" on the
majority of unix hosts and agreed with the kernel only by accident.
#hostname
Host name; "" if unknown.%COMPUTERNAME% rather than a GetComputerNameEx call: the narrow
form of that entry point renders the name through the process ANSI
code page, and the wide form returns UTF-16, which Axle cannot
marshal. The environment block is the same name, already UTF-8 by the
time the runtime's env shim hands it over.
#exePath
Absolute path to the running executable; "" on failure.
Non-throwing — use std/env::currentExe for the throwing form, which
is the surface that keeps the refusals apart. Here they all collapse:
this one returns a path and has no error to carry a reason in.
#username
Best-effort current user name. Reads the conventional login
environment variables in turn — $USER, then $LOGNAME (set by
Unix login shells), then $USERNAME (Windows) — so the lookup
survives shells and containers that populate only one of them.
Returns "" when none is set (a daemon or bare container with no
login session). Pure Axle: no syscall, just the inherited env.
#totalMemory
Total physical RAM in bytes. Not wired — there is no one syscall the
three targets share — so it raises UnsupportedOperationException
rather than silently returning 0, which a caller would divide by.
#availableMemory
Free (currently available) physical RAM in bytes. Not wired, for the
same reason as totalMemory: raises UnsupportedOperationException
rather than returning 0.