Standard library · System and tools

runtime

Facts about the running program: the system, the memory, the uptime and the build options.

import runtime

The runtime package answers questions about the running program and the machine under it: which system and processor, how many cores, how much memory, how long the program has been up and how it was compiled. It is what a /health route, a startup log line or a benchmark guard needs.

It gathers facts from os.platform and adds the uptime and the build flags. For details such as the host name or the kernel version, use os.platform directly; for the program's own allocation counts, mem; for timing a piece of code, time or the timers in debug.

Where the numbers come from:

SystemCpuCountTotalMemoryAvailableMemory, UsedMemory
Linuxa system callreads /proc/meminforeads /proc/meminfo
Windowsthe NUMBER_OF_PROCESSORS variableruns PowerShellruns PowerShell
macOS, BSDruns sysctlruns sysctlminus one

The things people get wrong:

  • The memory functions are not free everywhere. On Linux they read a small file, but on Windows each call starts PowerShell and takes a good part of a second. Cache the numbers, or refresh them on a timer, instead of reading them on every request.
  • Every number can be minus one when the system does not report it. Check before you do arithmetic.
  • The memory figures are for the whole machine, not this program. In a container you see the host's memory, not the container's limit.
  • The uptime counts from MarkStart. Without it the clock starts at the first UptimeMs call, so the first health check reports 0. It uses the wall clock, so changing the system time moves it.

A /health route

A load balancer, Docker's HEALTHCHECK or a monitoring service calls a health route every few seconds to see whether the program is alive. Call MarkStart first thing in main, so the uptime counts from the start of the program and not from the first request, and answer with a small JSON object built from the runtime facts.

runtime-health.salam
import runtime
import net.http
import net.router
import conv
import str

func health(ctx: i64):
    mut body := `{"status": "ok", "os": "` + runtime.OS() + `", "arch": "` + runtime.Arch() + `"`
    body = body + `, "cpus": ` + conv.FormatInt(runtime.CpuCount() as i64)
    body = body + `, "uptime_ms": ` + conv.FormatInt(runtime.UptimeMs())
    body = body + `, "used_memory": ` + conv.FormatInt(runtime.UsedMemory())
    body = body + `, "build": "` + runtime.BuildFlags() + `"}`
    http.Json(ctx, body)
end

func main:
    runtime.MarkStart()
    mut r := router.NewRouter()
    router.Get(r, "/health", health)
    mut s := http.NewServer(19734)
    http.Use(s, r)
    println http.RunBackground(s)
    res := http.Get("http://127.0.0.1:19734/health")
    body := http.Body(res)
    println http.Status(res), http.GetHeader(res, "content-type")
    println str.StartsWith(body, `{"status": "ok"`), str.Contains(body, `"uptime_ms": `)
end
Outputtrue 200 application/json true true

The example starts the server in the background with net.http and calls its own route, so it runs without anything else. The numbers in the body change on every run, so it prints only the status, the content type and two checks. A real body looks like {"status": "ok", "os": "linux", "arch": "x64", "cpus": 8, "uptime_ms": 5412, "used_memory": 6442450944, "build": "release"}.

Report memory in a readable way

TotalMemory and AvailableMemory return bytes, and minus one where the system does not report them. UsedMemory is the difference, or minus one when either is missing. Turn the bytes into MiB for people, and handle the minus one before doing any arithmetic, or a percentage of a negative number ends up on a dashboard.

runtime-memory.salam
import runtime
import conv

func mib(bytes: i64): str:
    if bytes < 0: ret "unknown" end
    ret conv.FormatInt(bytes / (1024 * 1024)) + " MiB"
end

func memory_line(total: i64, available: i64): str:
    if total < 0 or available < 0:
        ret "memory: not reported on this system"
    end
    percent := (total - available) * 100 / total
    ret "memory: " + mib(total - available) + " of " + mib(total) + " in use (" + conv.FormatInt(percent) + "%)"
end

func main:
    println memory_line(8589934592, 2147483648)
    println memory_line(17179869184, 15032385536)
    println memory_line(0 - 1, 0 - 1)
    line := memory_line(runtime.TotalMemory(), runtime.AvailableMemory())
    println line.Len() > 0
    used := runtime.UsedMemory()
    println used <= runtime.TotalMemory()
end
Outputmemory: 6144 MiB of 8192 MiB in use (75%) memory: 2048 MiB of 16384 MiB in use (12%) memory: not reported on this system true true

The first three lines use fixed numbers so the output is the same everywhere; the last two call the real functions.

Size a worker pool from the core count

A server or a batch job often starts one worker per core. CpuCount gives the cores that are online, but a sensible rule also lets the operator override it, puts a ceiling on very large machines and falls back to a small number when the count is unknown. Summary puts the main facts in one line, which is handy to log once at startup.

runtime-workers.salam
import runtime
import str

func pick_workers(cpus: int, configured: int): int:
    if configured > 0: ret configured end
    if cpus < 1: ret 2 end
    if cpus > 16: ret 16 end
    ret cpus
end

func main:
    println "8 cores, nothing configured:", pick_workers(8, 0)
    println "64 cores, nothing configured:", pick_workers(64, 0)
    println "core count unknown:", pick_workers(0 - 1, 0)
    println "configured by hand:", pick_workers(8, 3)
    workers := pick_workers(runtime.CpuCount(), 0)
    println "here:", workers >= 1 and workers <= 16
    line := runtime.Summary()
    println str.Contains(line, " cpus="), str.Contains(line, " build=")
end
Output8 cores, nothing configured: 8 64 cores, nothing configured: 16 core count unknown: 2 configured by hand: 3 here: true true true

A real Summary line looks like linux/x64 cpus=8 uptime_ms=3 build=release.

Know how the program was built

BuildFlags returns release for a --release build, or the checks that are compiled in, joined with commas: safe for the default development build with bounds checks, mem_debug and asan for the memory checking builds. IsSafeBuild, IsMemDebugBuild and IsAsanBuild test each one. These are fixed when the program is compiled, so checking them costs nothing.

runtime-build-check.salam
import runtime

func check_benchmark_build(): bool:
    flags := runtime.BuildFlags()
    if flags == "release":
        ret true
    end
    println "warning: this is a", flags, "build, so the timings would be too slow"
    if runtime.IsSafeBuild():
        println "  bounds checks are on; build with --release"
    end
    if runtime.IsAsanBuild() or runtime.IsMemDebugBuild():
        println "  memory checking is on; build without --asan or -DSALAM_MEM_DEBUG"
    end
    ret false
end

func main:
    if check_benchmark_build() == false:
        println "skipping the benchmark"
        ret
    end
    println "running the benchmark"
end
Outputwarning: this is a safe build, so the timings would be too slow bounds checks are on; build with --release skipping the benchmark

salam run makes a development build, which is why this example warns. Build it with salam build file.salam --release and the same program runs the benchmark. The same check is useful at startup of a server, to log a warning when a debug build reaches production by mistake.

Functions

OS

func OS(): str
The name of the operating system: linux, windows, mac, freebsd, wasm or unknown.
runtime-Summary.salam
import runtime

func main:
    runtime.MarkStart()
    println runtime.OS().Len() > 0, runtime.Arch().Len() > 0, runtime.CpuCount() >= 1
    free := runtime.AvailableMemory()
    used := runtime.UsedMemory()
    println runtime.TotalMemory() > 0, free > 0 or free == -1, used >= 0 or used == -1
    println runtime.UptimeMs() >= 0, runtime.UptimeSeconds() >= 0.0
    println runtime.IsAsanBuild(), runtime.IsMemDebugBuild()
    println runtime.IsSafeBuild() or not runtime.IsSafeBuild()
    println runtime.BuildFlags().Len() >= 0, runtime.Summary().Len() > 0
end
Outputtrue true true true true true true true false false true true true

Arch

func Arch(): str
The name of the processor architecture.

The example for this item is shown with the ones above: runtime-Summary.salam

CpuCount

func CpuCount(): int
The number of processor cores that are online, or minus one when it cannot be found.

The example for this item is shown with the ones above: runtime-Summary.salam

TotalMemory

func TotalMemory(): i64
The machine's total memory in bytes, or minus one. On Windows and macOS it starts a helper program, so it is slow there.

The example for this item is shown with the ones above: runtime-Summary.salam

AvailableMemory

func AvailableMemory(): i64
The memory in bytes the machine can still hand out, on Linux and Windows; minus one elsewhere.

The example for this item is shown with the ones above: runtime-Summary.salam

UsedMemory

func UsedMemory(): i64
Total minus available memory in bytes, or minus one when either is missing.

The example for this item is shown with the ones above: runtime-Summary.salam

MarkStart

func MarkStart()
Records the start instant for the uptime; call it at the top of main. Later calls do nothing.

The example for this item is shown with the ones above: runtime-Summary.salam

UptimeMs

func UptimeMs(): i64
The milliseconds since MarkStart, by the wall clock. If MarkStart was never called, the first call starts the count.

The example for this item is shown with the ones above: runtime-Summary.salam

UptimeSeconds

func UptimeSeconds(): f64
The uptime in seconds, with fractions.

The example for this item is shown with the ones above: runtime-Summary.salam

IsAsanBuild

func IsAsanBuild(): bool
True when the program was built with the ASan memory checker.

The example for this item is shown with the ones above: runtime-Summary.salam

IsMemDebugBuild

func IsMemDebugBuild(): bool
True when the program was built with allocation counting (-DSALAM_MEM_DEBUG or --asan).

The example for this item is shown with the ones above: runtime-Summary.salam

IsSafeBuild

func IsSafeBuild(): bool
True when the program was built with array bounds checking, which is every build except --release.

The example for this item is shown with the ones above: runtime-Summary.salam

BuildFlags

func BuildFlags(): str
release, or the checks that are compiled in joined with commas: safe, mem_debug, asan.

The example for this item is shown with the ones above: runtime-Summary.salam

Summary

func Summary(): str
One line with the system, architecture, cores, uptime and build flags, such as linux/x64 cpus=8 uptime_ms=3 build=release.

The example for this item is shown with the ones above: runtime-Summary.salam