shoney.arickathil
d7304f23ec
- Board renamed docs/plan/00-kanban.md -> docs/00-status.md and rebuilt: ▶ NEXT PLAN pointer (iteration 4 — emitter, corpus, `woc build`) then six buckets — stories, in progress, done, pending, discarded, learnings. It covered only the Rust runtime before, so the whole OOP track was invisible. All 16 inbound refs repointed; `Kanban:` banners renamed to `Status:`. - New discarded.md (settled rejections with reasons: inheritance, `abstract`, Money/SKU/Float, Dynamic/cast/macro/extern, AOT-to-C, Menhir, shared engine state) and learnings.md (plumbed≠enforced, vacuous goldens, exit-0-wrong- output, malloc-path ASan trick, deferred checks that never reach the VM). - RECOVERED docs/plan/exploration/blue-green-vm/00-vision.md — gone from disk, never committed (gitignored path), cited by five docs incl. principle 12. Root cause was broader: all seven forward-roadmap plans in docs/superpowers/plans/ were untracked and ignored, on one disk only. Dropped the docs ignore rules with a do-not-re-add note; added __pycache__/*.pyc. - Repaired broken links across docs/, 270 -> 36: fixes a regression from the earlier reference/ -> .dev/reference/ move (relative paths at ../../ and deeper were skipped), plus depth and reorg drift. The 36 residual point at content that does not exist and need decisions, not paths. - New spec docs/superpowers/specs/2026-08-10-logwatcher-gap-closure-design.md, applied: `and`/`or` verdict row; Part 3 gains `env` (six modules), swaps time.mono for iso/local, adds 22 bare core builtins; throw/time.mono/is cut (0 uses in the sample). Plan 8: Task 2 gains and/or, Task 5 drops throw, abstract+`is` task deleted, 8/9 renumber to 7/8. Plan 9 gains core builtins. Plan 10 gains the 307 -> 0 diagnostic gate. WO-E205 re-filed unreachable-by- design. types.ml header drops its false satisfaction-set claim. 00-code- review.md reduced to a stub — its rival Phase 1-4 roadmap retired.
77 lines
3.3 KiB
Markdown
77 lines
3.3 KiB
Markdown
# 03 — `timerfd`
|
|
|
|
Timers as file descriptors. Set an expiry with `timerfd_settime`, `read` the fd to retrieve the number of expirations, `epoll` notifies the loop when the timer fires. Drives everything in the runtime that needs a deadline without a separate timer thread: keepalives, debounce windows, checkpoint intervals.
|
|
|
|
## Kernel source
|
|
|
|
| Path | What |
|
|
| --- | --- |
|
|
| [`reference/linux/fs/timerfd.c`](../../../../.dev/reference/linux/fs/timerfd.c) | All three syscalls (`timerfd_create`, `timerfd_settime`, `timerfd_gettime`). |
|
|
| [`reference/linux/include/uapi/linux/timerfd.h`](../../../../.dev/reference/linux/include/uapi/linux/timerfd.h) | `TFD_*` flags. |
|
|
|
|
## Man pages
|
|
|
|
`man 2 timerfd_create`, `man 2 timerfd_settime`, `man 2 timerfd_gettime`.
|
|
|
|
## Rust FFI via `libc`
|
|
|
|
```rust
|
|
use libc::{timerfd_create, timerfd_settime, timerfd_gettime};
|
|
use libc::{itimerspec, timespec};
|
|
use libc::{TFD_CLOEXEC, TFD_NONBLOCK, TFD_TIMER_ABSTIME};
|
|
use libc::{CLOCK_MONOTONIC, CLOCK_REALTIME};
|
|
```
|
|
|
|
## Direct-syscall example
|
|
|
|
```rust
|
|
unsafe {
|
|
let fd = libc::timerfd_create(
|
|
libc::CLOCK_MONOTONIC,
|
|
libc::TFD_CLOEXEC | libc::TFD_NONBLOCK,
|
|
);
|
|
if fd < 0 { return Err(io::Error::last_os_error()); }
|
|
|
|
// one-shot: fire in 150ms, no interval
|
|
let spec = libc::itimerspec {
|
|
it_value: libc::timespec { tv_sec: 0, tv_nsec: 150_000_000 },
|
|
it_interval: libc::timespec { tv_sec: 0, tv_nsec: 0 },
|
|
};
|
|
// periodic: replace it_interval with the period, e.g. { tv_sec: 1, tv_nsec: 0 }
|
|
|
|
if libc::timerfd_settime(fd, 0, &spec, std::ptr::null_mut()) < 0 {
|
|
return Err(io::Error::last_os_error());
|
|
}
|
|
|
|
// register fd on the epoll loop; on EPOLLIN:
|
|
let mut expirations: u64 = 0;
|
|
libc::read(fd, &mut expirations as *mut _ as *mut _, 8);
|
|
// expirations > 0 means the timer fired. Usually 1 for a oneshot,
|
|
// could be >1 for a periodic timer whose consumer missed ticks.
|
|
}
|
|
```
|
|
|
|
## Key flags
|
|
|
|
| Flag | Meaning |
|
|
| --- | --- |
|
|
| `CLOCK_MONOTONIC` | Steady clock; immune to wall-clock jumps. **Default choice for runtime timers.** |
|
|
| `CLOCK_REALTIME` | Wall clock; jumps when NTP corrects or user sets time. Avoid unless you need calendar semantics. |
|
|
| `TFD_CLOEXEC` | Close on exec. Always set. |
|
|
| `TFD_NONBLOCK` | `read` doesn't block when expirations == 0. Required when on `epoll`. |
|
|
| `TFD_TIMER_ABSTIME` | Interpret `it_value` as absolute (not relative). Passed to `timerfd_settime`'s `flags`, not at create. |
|
|
|
|
## Gotchas
|
|
|
|
- **Reads are always 8 bytes.** The value is an expiration count.
|
|
- **Disarming is `timerfd_settime(fd, 0, &{0,0,0,0}, NULL)`** — a zero spec cancels pending fires.
|
|
- **Re-arming a periodic timer** replaces the spec atomically; no "pause then resume" surface.
|
|
- **Resolution is nanosecond-granular but scheduling can slip.** Don't use for sub-millisecond accuracy — use a busy loop or hardware timer for that.
|
|
|
|
## Used by
|
|
|
|
[`02-event-loop-epoll.md`](../../done/02-event-loop-epoll.md) — housekeeping timers. [`07-inotify-content-watcher.md`](../../07-inotify-content-watcher.md) — 150 ms debounce window after an inotify burst. Future subscription phase — keepalive pings to long-lived connections.
|
|
|
|
## v1 port source
|
|
|
|
[`reference/crates/wo-event/src/timerfd.rs`](../../../../.dev/reference/crates/wo-event/src/timerfd.rs) (91 LOC) — `TimerFd { oneshot(dur), periodic(dur), disarm, read_expirations }`.
|