# `os`

`a` runs scripts in a sandbox, so the standard `os` table is trimmed to its
safe, time-related functions — `os.time`, `os.clock`, `os.date`,
`os.difftime`, `os.getenv` — while the parts that touch the system
(`os.execute`, `os.remove`, `os.exit`, …) are removed. To that trimmed table `a`
adds two functions: a high-resolution clock and an async sleep.

```lua
local t0 = os.microtime()
os.sleep(0.25)
print(string.format("waited %.3fs", os.microtime() - t0))  --> waited ~0.250s
```

## `os.microtime()`

Return the current time as a Unix timestamp in **seconds, as a float** with
sub-second precision — unlike `os.time`, which is whole seconds only. It is the
right tool for measuring elapsed time:

```lua
local start = os.microtime()
doSomeWork()
local elapsed = os.microtime() - start
log.info(string.format("took %.1f ms", elapsed * 1000))
```

It reads the system wall clock, so it tracks real time (and can jump if the clock
is adjusted); for interval timing the difference of two readings is what you
want.

## `os.sleep(seconds)`

Pause for `seconds` (a float, so `os.sleep(0.1)` is 100 ms). This is an **async**
sleep: it suspends the script on the runtime instead of blocking the OS thread,
so concurrent work keeps running while it waits.

```lua
os.sleep(1)      -- one second
os.sleep(0.05)   -- 50 milliseconds
```

`seconds` must be a non-negative finite number.

Because the sleep suspends rather than blocks, sibling tasks started with
[`task.join`](concurrency.md) make progress during the wait — that is what lets
several sleeps (or requests, or queries) overlap:

```lua
-- finishes in ~0.3s, not 0.6s — the sleeps overlap
task.join(
    function() os.sleep(0.3) end,
    function() os.sleep(0.2) end,
    function() os.sleep(0.1) end
)
```

One caveat applies to coroutines you drive yourself with `coroutine.wrap` /
`coroutine.resume`: there, `os.sleep` does not actually wait. See
[Self-driven coroutines](concurrency.md#self-driven-coroutines) for the full
explanation — the rule is to run anything that needs to sleep through
`task.join`.

## Notes

- **The sandbox keeps the time functions.** `os.time`, `os.clock`, `os.date`,
  `os.difftime`, and `os.getenv` work as in stock Lua; system-mutating functions
  are not present.
- **`microtime` for durations, `time` for timestamps.** Use `os.microtime` when
  you need sub-second precision or are timing an interval; `os.time` when whole
  seconds suffice.
- **`sleep` is cooperative.** It yields to the runtime, so it is cheap to sleep
  inside concurrent tasks — see [Concurrency](concurrency.md).