OS Introspection (std.os)

Inspect the host operating system platform, hostname, CPU architecture, and physical RAM memory states:

---

Host Platform & Architecture

Retrieve information about the host platform, architecture, and machine hostname:

import std.os

println($"Operating System Name: {os.name()}")     // e.g., "windows", "linux", "macos"
println($"Operating System Family: {os.family()}") // e.g., "windows", "unix"
println($"CPU Architecture: {os.arch()}")           // e.g., "x86_64", "aarch64"
println($"Host Name: {os.hostname()}")             // e.g., "my-laptop"

---

System Memory (os.mem)

Query system physical memory states in bytes using os.mem(), returning a typed memStates struct:

import std.os

let memory = os.mem()

let totalGb = memory.totalMemory / 1024 / 1024 / 1024
let usedGb = memory.usedMemory / 1024 / 1024 / 1024
let availableGb = memory.availableMemory / 1024 / 1024 / 1024
let freeGb = memory.freeMemory / 1024 / 1024 / 1024

println($"Total: {totalGb} GB")
println($"Used: {usedGb} GB")
println($"Available: {availableGb} GB")
println($"Free: {freeGb} GB")

Note

freeMemory represents memory completely untouched by the kernel, while availableMemory accounts for reclaimable disk caches and buffers. For calculating memory currently in use, use memory.usedMemory or totalMemory - availableMemory.

---

Process Memory & CPU Introspection

Flame provides high-precision, non-blocking telemetry for monitoring the currently running process without external profiling tools.

Complete Process Telemetry (os.processMemory)

os.processMemory() queries the process statistics directly. On Linux, it uses /proc/self/statm and getrusage(RUSAGE_SELF) for microsecond-level metrics with zero memory allocation and zero thread suspension.

import std.os

let proc = os.processMemory()

println($"Resident Memory (RSS): {proc.rssMb} MB ({proc.rss} bytes)")
println($"Virtual Memory: {proc.virtualMb} MB")
println($"Process CPU Usage: {proc.cpu}%")
println($"Total CPU Time: {proc.cpuTime}s")

Direct Process Memory (os.memoryUsage)

If you only need the current memory footprint in megabytes (MB) for logging or benchmarking:

import std.os

let memMb = os.memoryUsage()
println($"Memory consumption: {memMb} MB")

Direct Process CPU (os.cpuUsage)

To measure process CPU utilization:

import std.os

let cpuPercent = os.cpuUsage()
println($"Current CPU: {cpuPercent}%")

---

Benchmarking Example

Combine std.time and std.os to benchmark high-throughput data processing algorithms:

import std.time
import std.os
import "benchmark.json" as data

let start = time.now()

// Execute intensive workload...
let mut sum = 0
for user in data.users {
    if user.active {
        sum += user.id
    }
}

let elapsed = time.now() - start
let mem = os.processMemory()
let cpu = os.cpuUsage()

println($"Processed {data.users.len()} items")
println($"Elapsed time: {elapsed}")
println($"Peak memory: {mem.rssMb} MB")
println($"Virtual memory: {mem.virtualMb} MB")
println($"CPU utilization: {cpu}%")

---

API Reference

Functions

Method	Arguments	Returns	Description
os.name	None	String	Returns the OS name identifier (e.g., "windows", "linux", "macos").
os.arch	None	String	Returns the host CPU processor architecture (e.g., "x86_64", "aarch64").
os.family	None	String	Returns the general OS operating platform family (e.g., "windows", "unix").
os.hostname	None	String	Returns the host machine name / hostname.
os.mem	None	memStates	Returns overall system physical memory statistics in bytes.
os.processMemory	None	ProcessMemoryInfo	Returns the current process Resident Set Size (rss, rssMb), virtual memory (virtualMb), CPU percentage (cpu), and cumulative CPU seconds (cpuTime).
os.memoryUsage	None	Float	Returns the current process resident memory consumption directly in Megabytes (MB).
os.cpuUsage	None	Float	Returns the current process CPU usage percentage.

ProcessMemoryInfo Struct

Field	Type	Description
rss	Int	Resident Set Size (physical memory occupied by the process) in bytes.
rssMb	Float	Resident Set Size converted to Megabytes, rounded to 2 decimal places.
virtualMb	Float	Total virtual memory mapped by the process in Megabytes.
cpu	Float	Process CPU utilization percentage.
cpuTime	Float	Cumulative user and system CPU time consumed by the process in seconds.

memStates Struct

Field	Type	Description
totalMemory	Int	Total system physical RAM in bytes.
usedMemory	Int	System physical RAM currently in use in bytes.
availableMemory	Int	System physical RAM available to start new applications without swapping in bytes.
freeMemory	Int	Completely unallocated system physical RAM in bytes.