swift-system-clock

Implements SystemClock which reads operating system clocks with no overhead.

Supports Darwin (Apple platforms), Linux (Including Android), Windows, FreeBSD, OpenBSD¹, WASI and more.
Also compiles (merely) on embedded platforms in a similar fashion to Swift standard library's ContinuousClock.

Usage

Default Clocks

SystemClock conforms to Clock, so it works just like stdlib's ContinuousClock/SuspendingClock:

import SystemClock

let elapsed: CompactDuration = SystemClock.suspending.measure {
    expensiveWork()
}

let now = SystemClock.realtime.now

Note

SystemClock defaults to using CompactDuration although Swift's Duration is also supported.
CompactDuration is a lower-precision Duration that only keeps nanoseconds.
The extra precision is unneeded 99+% of the time in a system-clock context and would be a waste of resources.

Custom Clocks

You can hand-craft a system clock that uses your desired clocks on each platform:

/// `SystemClock` == `GenericSystemClock<CompactDuration>`
let realtimeClock = SystemClock(
    darwin: .realtime,
    linux: .realtime,
    windows: .systemTimePrecise,
    freebsd: .realtimePrecise,
    openbsd: .realtime,
    wasi: .realtime,
    fallback: .realtime
)

/// You can use `Swift.Duration` as well although `CompactDuration` is generally recommended.
let processCPUTimeClock = GenericSystemClock<Swift.Duration>(
    darwin: .processCPUTime,
    linux: .processCPUTime,
    windows: .processTime,
    freebsd: .processCPUTime,
    openbsd: .processCPUTime,
    wasi: .monotonic,
    fallback: .monotonic
)

Every Apple platform takes darwin. Android takes linux.
Unidentified platforms or platforms with no libc will take fallback which uses std::chrono clocks.

Note

SystemClock will only compile code for the platform you're deploying to.
Essentially, SystemClock is a multi-platform library, but that comes for free with no overhead.

Sleeping

Warning

SystemClock does not support sleeping.
sleep(until:tolerance:) only exists as a requirement of the Clock protocol, and fatal-errors when called.
Task.sleep(for:clock:) and Task.sleep(until:clock:) route through it, so they'll crash too.
Use standard library's ContinuousClock or SuspendingClock instead for sleeping.

Cheat Sheet

For convenience, here is a cheat sheet that should work for most users:

If you want to	Use
... know what time it is	`realtime`
... stamp a log line, cheaply	`realtimeCoarse`

If you want to measure how long	Use
... some work took, including system sleeps	`continuous` / `continuousCoarse`
... some work took, excluding system sleeps	`suspending` / `suspendingCoarse`
... the process spent running on all CPUs, combined	`processCPUTime`
... the thread spent running on any CPU core	`threadCPUTime`
... the process spent running in user mode on all CPUs, combined	`processUserTime`
... the thread spent running in user mode on any CPU core	`threadUserTime`
... the kernel spent running for this process on all CPUs, combined	`processSystemTime`
... the kernel spent running for this thread on any CPU core	`threadSystemTime`

"coarse" clocks are cheaper but also less precise. Sometimes you'll have to make that trade-off.
An example of a system sleep is when you close your laptop's lid.
An example of the kernel running on behalf of your process is when you read a file, or send data over a socket.
Generally, [process/thread]UserTime + [process/thread]SystemTime ~= [process/thread]CPUTime.

Note

On WASI, wasi-libc exposes 2 clocks only: monotonic and realtime.
When a clock is unavailable on any platform, SystemClock simply falls back to the best available fit.

Platform Clocks

This library supports every clock Unix systems expose via clock_gettime(2).
For Windows, this library follows Acquiring high-resolution time stamps.
In few cases, for example for processUserTime and threadUserTime, this library uses alternative functions such as getrusage(2).

Supported Clocks

Here is a list of all supported clocks on each platform.

macOS was measured on an M1 Pro (arm64 Apple silicon) under macOS 27, bare metal.
Windows on an Intel Core i7-10750H (x86_64) under Windows 11, bare metal.
Linux on Ubuntu 24.04 (kernel 6.8, HZ=1000) in a dedicated-core AMD EPYC Milan x86_64 VM from Hetzner.
FreeBSD 15.1 and OpenBSD 7.9 in arm64 QEMU virtual machines on the same Mac, where kern.hz is 100.
WASI on the same Mac under wasmtime 48 (primary source), Node 26 (uvwasi), Bun 1.3 and WasmKit 0.1.6.

Note

The measured values are meant as general hints.
For better accuracy, measure under your own specific hardware and kernel.
If you find a value generally/widely incorrect, please file an issue or open a pull request for it.

Darwin (Apple platforms)

realtime (CLOCK_REALTIME)

clock_gettime(3)

Measures Wall time, counted from 1970-01-01 UTC

Property	Value
Reacts to OS time changes	❌ Yes
Reacts to NTP changes	❌ Yes
Counts system suspension times	❌ Yes
Advances while thread is de-scheduled	❌ Yes
Might appear to go backwards	❌ Yes
Reads a cached value	✅ No
Max staleness	✅ None
Warm read cost	~ 12ns @ 4GHz
Cold read cost	~ 200ns @ 4GHz
Step granularity	1µs

monotonic (CLOCK_MONOTONIC)

clock_gettime(3)