silk.system.system_info.

The SystemInfo effect: facts about the computer and the running process that the operating system reports, such as the host name, the memory, the processors, the network interfaces, the current user, and the resource usage of the process.

When to use#

Require &mut SystemInfo in code that reports on the host or on its own process, such as an os module of a language runtime, a status page, or a tool that sizes its work to the memory. A test can provide fixed values. silk.system.system_info_native has the provider for native programs.

Details#

Each operation asks the operating system again, so two calls can give different values. The operations never wait for an event: each one makes a few system calls or reads a few files of the system, and returns.

Text that the system reports, such as a host name, a path, or a user name, is returned as owned Bytes, because the system does not promise UTF-8. Use String.fromUtf8 when you need text.

Environment variables are not read. A runtime that follows HOME or TMPDIR reads them with silk.system.host_input, and uses UserInfo when HOME is not set.

Errors#

Examples#

Read the memory of the computer#

silk
import silk.core.effect { Effect }
import silk.core.result { Result }
import silk.system.system_info { MemoryInfo, SystemInfo, SystemInfoError }
import silk.system.system_info_native { OsSystemInfo }

pub effect fn main() -> i32 {
  let mut provider = OsSystemInfo.make()
  let result = run Effect.result(SystemInfo.memory()) |> Effect.provideMut<SystemInfo>(&mut provider)
  return match move result {
    Result<MemoryInfo, SystemInfoError>.Success { value } => {
      // The free memory is never more than the total.
      if value.total == 0 || value.free > value.total { 1 } else { 0 }
    }
    Result<MemoryInfo, SystemInfoError>.Failure { .. } => 1
  }
}

Import as SystemInfo with import silk.system.system_info { SystemInfo }.

Public declarations: 12.

SystemInfoOperation#

silk
pub enum SystemInfoOperation

The operation of SystemInfo that failed.

HostName#

silk
HostName

Reading the host name, in SystemInfo.hostName.

Kernel#

silk
Kernel

Reading the kernel names, in SystemInfo.kernel.

Uptime#

silk
Uptime

Reading the time since boot, in SystemInfo.uptime.

LoadAverage#

silk
LoadAverage

Reading the load averages, in SystemInfo.loadAverage.

Memory#

silk
Memory

Reading the memory counts, in SystemInfo.memory.

Processors#

silk
Processors

Reading the processors, in SystemInfo.processors.

Parallelism#

silk
Parallelism

Reading the processors that the process may use, in SystemInfo.availableParallelism.

NetworkInterfaces#

silk
NetworkInterfaces

Reading the network interfaces, in SystemInfo.networkInterfaces.

User#

silk
User

Reading a user account, in SystemInfo.currentUser or SystemInfo.user.

Priority#

silk
Priority

Reading a scheduling priority, in SystemInfo.priority.

SetPriority#

silk
SetPriority

Changing a scheduling priority, in SystemInfo.setPriority.

ResourceUsage#

silk
ResourceUsage

Reading resource usage, in SystemInfo.resourceUsage.

ResidentSetSize#

silk
ResidentSetSize

Reading the resident memory of the process, in SystemInfo.residentSetSize.

ExecutablePath#

silk
ExecutablePath

Reading the path of the program file, in SystemInfo.executablePath.

SystemInfoError#

silk
pub struct SystemInfoError

A failed SystemInfo operation: which one, and the native error code.

Details#

code is the errno value of the failed call, such as 2 (ENOENT) for a user id that has no account, 3 (ESRCH) for a process that does not exist, or 13 (EACCES) for a priority that the process may not set. For a failed Mach call on macOS, it is the kern_return_t value. It is 0 when the system answered with data that is not valid.

Field operation#

silk
pub operation: SystemInfoOperation

The operation that failed.

Field code#

silk
pub code: i32

The native error code, or 0 for data that is not valid.

Implementation Copy for SystemInfoError#

silk
impl Copy for SystemInfoError

KernelInfo#

silk
pub struct KernelInfo

The names of the running kernel, as uname reports them.

Details#

On Linux, name is Linux, and on macOS it is Darwin. release is the kernel release, such as 6.8.0-45-generic, version is the build text of the kernel, and machine is the hardware name, such as x86_64 or arm64.

Field name#

silk
pub name: Bytes

The kernel name, such as Linux or Darwin.

Field release#

silk
pub release: Bytes

The kernel release, such as 6.8.0-45-generic.

Field version#

silk
pub version: Bytes

The build text of the kernel.

Field machine#

silk
pub machine: Bytes

The hardware name, such as x86_64 or arm64.

MemoryLimit#

silk
pub struct MemoryLimit

A memory limit of a control group, and the memory that the group uses now.

Details#

Linux reports it for a process in a cgroup with a memory.max (cgroup v2) or a memory.limit_in_bytes (cgroup v1) limit, such as in a container.

Field bytes#

silk
pub bytes: u64

The limit, in bytes.

Field used#

silk
pub used: u64

The memory that the group uses now, in bytes.

Implementation Copy for MemoryLimit#

silk
impl Copy for MemoryLimit

MemoryInfo#

silk
pub struct MemoryInfo

The memory of the computer, in bytes.

Details#

free is memory that nothing uses. available also counts memory that the system can take back at once, such as file caches, so it is at least free on Linux (MemAvailable). On macOS, available is the free page count, the same as free.

limit is the memory limit of the control group of the process, when it has one. A process with a limit can use at most limit.bytes - limit.used more bytes, also when available is larger.

Field total#

silk
pub total: u64

The physical memory, in bytes.

Field free#

silk
pub free: u64

The memory that nothing uses, in bytes.

Field available#

silk
pub available: u64

The memory that a new allocation can get without swapping, in bytes.

Field limit#

silk
pub limit: Option<MemoryLimit>

The memory limit of the control group of the process, if there is one.

Implementation Copy for MemoryInfo#

silk
impl Copy for MemoryInfo

ProcessorTimes#

silk
pub struct ProcessorTimes

The time that one processor spent in each state since boot, in milliseconds.

Field user#

silk
pub user: u64

Time in user mode.

Field nice#

silk
pub nice: u64

Time in user mode for processes with a lower priority.

Field system#

silk
pub system: u64

Time in kernel mode.

Field idle#

silk
pub idle: u64

Time with nothing to do.

Field interrupt#

silk
pub interrupt: u64

Time spent on hardware interrupts. It is 0 on macOS.

Implementation Copy for ProcessorTimes#

silk
impl Copy for ProcessorTimes

ProcessorInfo#

silk
pub struct ProcessorInfo

One logical processor: its model, its speed, and its times.

Details#

model is the model text of the system, such as Intel(R) Xeon(R) CPU @ 2.20GHz, or unknown when the system has none. speed is the current clock speed in MHz, or 0 when the system does not report it, as on Apple silicon.

Field model#

silk
pub model: Bytes

The model text, or unknown.

Field speed#

silk
pub speed: u32

The clock speed in MHz, or 0 when it is not known.

Field times#

silk
pub times: ProcessorTimes

The time that the processor spent in each state since boot.

NetworkInterface#

silk
pub struct NetworkInterface

One address of a network interface that is up.

Details#

An interface with more than one address gives one entry for each address, with the same name. mac is the hardware address of the interface, or all zeros when it has none, such as a loopback interface. internal is true for a loopback interface. scopeId is the scope of an IPv6 address, such as the interface index of a link-local address, and 0 for IPv4.

Field name#

silk
pub name: Bytes

The interface name, such as eth0 or en0.

Field address#

silk
pub address: IpAddress

The address.

Field netmask#

silk
pub netmask: IpAddress

The network mask, of the same family as the address.

Field mac#

silk
pub mac: [u8; 6]

The hardware address, or all zeros.

Field internal#

silk
pub internal: bool

True for a loopback interface.

Field scopeId#

silk
pub scopeId: u32

The IPv6 scope, or 0.

UserInfo#

silk
pub struct UserInfo

A user account, from the user database of the system.

Details#

home and shell are empty when the account has none.

Field name#

silk
pub name: Bytes

The login name.

Field uid#

silk
pub uid: u32

The user id.

Field gid#

silk
pub gid: u32

The id of the primary group.

Field home#

silk
pub home: Bytes

The home directory.

Field shell#

silk
pub shell: Bytes

The login shell.

UsageScope#

silk
pub enum UsageScope

Which resource usage SystemInfo.resourceUsage reports.

Process#

silk
Process

The whole process: all its threads.

Thread#

silk
Thread

The calling thread.

ResourceUsage#

silk
pub struct ResourceUsage

The resources that a process or a thread used, as getrusage reports them.

Details#

Times are in microseconds. maxResidentBytes is the largest resident memory so far, in bytes on every system. The counters that a system does not keep are 0: Linux keeps no sharedMemory, unsharedData, unsharedStack, swaps, messagesSent, messagesReceived, or signals. For UsageScope.Thread on macOS, only the two times are reported.

Field userMicroseconds#

silk
pub userMicroseconds: u64

CPU time in user mode, in microseconds.

Field systemMicroseconds#

silk
pub systemMicroseconds: u64

CPU time in kernel mode, in microseconds.

Field maxResidentBytes#

silk
pub maxResidentBytes: u64

The largest resident memory so far, in bytes.

Field sharedMemory#

silk
pub sharedMemory: u64

The integral shared memory size (ru_ixrss).

Field unsharedData#

silk
pub unsharedData: u64

The integral unshared data size (ru_idrss).

Field unsharedStack#

silk
pub unsharedStack: u64

The integral unshared stack size (ru_isrss).

Field minorFaults#

silk
pub minorFaults: u64

Page faults that needed no input or output.

Field majorFaults#

silk
pub majorFaults: u64

Page faults that needed input or output.

Field swaps#

silk
pub swaps: u64

Times the process was swapped out.

Field blockInputs#

silk
pub blockInputs: u64

Block input operations.

Field blockOutputs#

silk
pub blockOutputs: u64

Block output operations.

Field messagesSent#

silk
pub messagesSent: u64

IPC messages sent.

Field messagesReceived#

silk
pub messagesReceived: u64

IPC messages received.

Field signals#

silk
pub signals: u64

Signals received.

Field voluntaryContextSwitches#

silk
pub voluntaryContextSwitches: u64

Context switches because the process waited.

Field involuntaryContextSwitches#

silk
pub involuntaryContextSwitches: u64

Context switches because a higher priority process ran, or the time slice ended.

Implementation Copy for ResourceUsage#

silk
impl Copy for ResourceUsage

SystemInfo#

silk
pub service SystemInfo

The effect that reads facts about the computer and the running process from the operating system.

When to use#

Require &mut SystemInfo in code that reports on the host or on its own process, such as an os module of a language runtime. A test can provide fixed values. Use the provider in silk.system.system_info_native in a native program.

Details#

Each operation asks the system again and returns without waiting for an event. Text that the system reports is owned Bytes, because the system does not promise UTF-8. Environment variables are not read: a runtime that follows HOME or TMPDIR reads them with silk.system.host_input. Only SystemInfo.setPriority changes the system.

Operation hostName#

silk
effect fn hostName() -> Bytes ! SystemInfoError | OutOfMemoryError ? &mut SystemInfo | &mut Allocator

Returns the host name of the computer.

Errors#

  • SystemInfoError with HostName if the system cannot report it.

  • OutOfMemoryError if the Allocator cannot supply the copy.

Operation kernel#

silk
effect fn kernel() -> KernelInfo ! SystemInfoError | OutOfMemoryError ? &mut SystemInfo | &mut Allocator

Returns the names of the running kernel: name, release, version, and hardware.

Errors#

  • SystemInfoError with Kernel if the system cannot report them.

  • OutOfMemoryError if the Allocator cannot supply the copies.

Operation uptime#

silk
effect fn uptime() -> u64 ! SystemInfoError ? &mut SystemInfo

Returns the time since the computer started, in nanoseconds. It counts time asleep.

Errors#

Operation loadAverage#

silk
effect fn loadAverage() -> [f64; 3] ! SystemInfoError ? &mut SystemInfo

Returns the 1, 5, and 15 minute load averages, in this order.

Details#

A load average is the mean number of threads that ran or waited to run.

Errors#

Operation memory#

silk
effect fn memory() -> MemoryInfo ! SystemInfoError ? &mut SystemInfo

Returns the total, free, and available memory of the computer, and the memory limit of the process when it has one.

Errors#

Operation processors#

silk
effect fn processors() -> List<ProcessorInfo> ! SystemInfoError | OutOfMemoryError ? &mut SystemInfo | &mut Allocator

Returns one entry for each logical processor that is online, in the order of the system.

Errors#

  • SystemInfoError with Processors if the system cannot report them.

  • OutOfMemoryError if the Allocator cannot supply the list.

Operation availableParallelism#

silk
effect fn availableParallelism() -> usize ! SystemInfoError ? &mut SystemInfo

Returns the number of processors that the process may run on, at least 1.

Details#

On Linux, it counts the CPU affinity mask of the process, so it can be less than the number of processors online. On macOS, it is the number of processors online.

Errors#

Operation networkInterfaces#

silk
effect fn networkInterfaces() -> List<NetworkInterface> ! SystemInfoError | OutOfMemoryError ? &mut SystemInfo | &mut Allocator

Returns one entry for each address of each network interface that is up and running.

Details#

Only IPv4 and IPv6 addresses are listed. An interface with no address is not listed.

Errors#

  • SystemInfoError with NetworkInterfaces if the system cannot report them.

  • OutOfMemoryError if the Allocator cannot supply the list.

Operation currentUser#

silk
effect fn currentUser() -> UserInfo ! SystemInfoError | OutOfMemoryError ? &mut SystemInfo | &mut Allocator

Returns the account of the effective user of the process.

Errors#

  • SystemInfoError with User if the account cannot be read, with code 2 (ENOENT) if the user id has no account.

  • OutOfMemoryError if the Allocator cannot supply the copies.

Operation user#

silk
effect fn user(uid: u32) -> UserInfo ! SystemInfoError | OutOfMemoryError ? &mut SystemInfo | &mut Allocator

Returns the account of user id uid.

Errors#

  • SystemInfoError with User if the account cannot be read, with code 2 (ENOENT) if uid has no account.

  • OutOfMemoryError if the Allocator cannot supply the copies.

Operation priority#

silk
effect fn priority(pid: i32) -> i32 ! SystemInfoError ? &mut SystemInfo

Returns the scheduling priority of process pid, from -20 (first) to 19 (last). Process 0 is the calling process.

Errors#

  • SystemInfoError with Priority, with code 3 (ESRCH) if no process has the id.

Operation setPriority#

silk
effect fn setPriority(pid: i32, value: i32) -> () ! SystemInfoError ? &mut SystemInfo

Sets the scheduling priority of process pid to value, from -20 (first) to 19 (last). Process 0 is the calling process. The system limits a value outside the range to it.

Errors#

  • SystemInfoError with SetPriority, with code 3 (ESRCH) if no process has the id, or 13 (EACCES) or 1 (EPERM) if the process may not set that priority.

Operation resourceUsage#

silk
effect fn resourceUsage(scope: UsageScope) -> ResourceUsage ! SystemInfoError ? &mut SystemInfo

Returns the resources that the process or the calling thread used.

Errors#

Operation residentSetSize#

silk
effect fn residentSetSize() -> u64 ! SystemInfoError ? &mut SystemInfo

Returns the resident memory of the process now, in bytes.

Errors#

Operation executablePath#

silk
effect fn executablePath() -> Bytes ! SystemInfoError | OutOfMemoryError ? &mut SystemInfo | &mut Allocator

Returns the absolute path of the program file of the process, with links resolved.

Errors#

  • SystemInfoError with ExecutablePath if the system cannot report it.

  • OutOfMemoryError if the Allocator cannot supply the copy.

Operation processId#

silk
effect fn processId() -> i32 ? &mut SystemInfo

Returns the id of the process.

Operation parentProcessId#

silk
effect fn parentProcessId() -> i32 ? &mut SystemInfo

Returns the id of the parent process.

Implementation SystemInfo#

silk
impl SystemInfo

Associated function failure#

silk
pub fn failure(operation: SystemInfoOperation, code: i32) -> SystemInfoError

Returns a SystemInfoError for operation and the native error code code. Providers use it when an operation fails.

Category: System.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.

View the source of this page