<time> Internal Library

The <time> internal library provides precision-oriented timing APIs.

Import

import "<time>"

Or as a named import:

import t "<time>"

Module Metadata

• name -> "time"
• available -> true
• platform -> "windows" on Windows, "posix" on non-Windows
• version -> internal module version string

API

sleep(seconds) -> bool

Sleeps for a duration in seconds.

• Accepts int or float.
• Negative values are clamped to 0.
• Returns true on success.

On Windows, sleep uses a hybrid approach:

• coarse sleep (Sleep) for most of the interval
• high-resolution trim using QueryPerformanceCounter

This improves precision compared with coarse-only sleeping.

sleep_ms(milliseconds) -> bool

Millisecond convenience wrapper around sleep.

• Accepts int or float milliseconds.
• Negative values are clamped to 0.

time() -> float

Returns current wall-clock epoch time in seconds.

• On Windows: sourced from GetSystemTimePreciseAsFileTime.
• On POSIX: sourced from clock_gettime(CLOCK_REALTIME) when available.

monotonic() -> float

Returns monotonic time in seconds.

Use this for elapsed duration measurement.

• Not affected by wall-clock adjustments.
• Recommended for profiling and timeout logic.

perf_counter() -> float

High-resolution performance counter in seconds.

In this implementation it maps to the same monotonic source as monotonic().

perf_frequency() -> float

Counter frequency in ticks-per-second.

• On Windows, returns QueryPerformanceFrequency value.
• On non-Windows, returns 1_000_000_000.0 (nanosecond base convention).

Precision Guidance

For elapsed timing:

1. read t0 = monotonic()
2. run work
3. read t1 = monotonic()
4. compute dt = t1 - t0

Avoid using time() for short-interval measurement because wall-clock time can jump.

Examples

Basic elapsed-time measurement

import "<time>"

var t0 = monotonic()
sleep(0.02)
var t1 = monotonic()

display("elapsed: " + (t1 - t0))

Millisecond sleep

import "<time>"

sleep_ms(150)

Named import style

import tm "<time>"

var start = tm.perf_counter()
## ... work ...
var elapsed = tm.perf_counter() - start
display(elapsed)