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.6 KiB
Markdown
77 lines
3.6 KiB
Markdown
# 04 — `signalfd`
|
|
|
|
Unix signals as file descriptors. `signalfd(fd, mask)` installs a mask on the process and returns an fd that becomes readable when any masked signal arrives. Replaces signal handlers entirely — no `sigaction`, no re-entrancy minefield, no interrupted syscalls. The whole `wo` binary's shutdown path is one `signalfd` on the event loop.
|
|
|
|
## Kernel source
|
|
|
|
| Path | What |
|
|
| --- | --- |
|
|
| [`reference/linux/fs/signalfd.c`](../../../../.dev/reference/linux/fs/signalfd.c) | `SYSCALL_DEFINE4(signalfd4, ...)` + `signalfd_dequeue`. |
|
|
| [`reference/linux/include/uapi/linux/signalfd.h`](../../../../.dev/reference/linux/include/uapi/linux/signalfd.h) | `struct signalfd_siginfo`, `SFD_*` flags. |
|
|
| [`reference/linux/kernel/signal.c`](../../../../.dev/reference/linux/kernel/signal.c) | Background: `sigprocmask`, pending-signal dequeue. |
|
|
|
|
## Man pages
|
|
|
|
`man 2 signalfd`, `man 7 signal`.
|
|
|
|
## Rust FFI via `libc`
|
|
|
|
```rust
|
|
use libc::{signalfd, signalfd_siginfo, sigset_t};
|
|
use libc::{sigemptyset, sigaddset, sigprocmask};
|
|
use libc::{SFD_CLOEXEC, SFD_NONBLOCK, SIG_BLOCK, SIG_UNBLOCK};
|
|
use libc::{SIGINT, SIGTERM, SIGHUP, SIGQUIT};
|
|
```
|
|
|
|
## Direct-syscall example
|
|
|
|
```rust
|
|
unsafe {
|
|
// 1. Block the signals in the thread so the kernel delivers them via the fd instead
|
|
let mut mask: sigset_t = std::mem::zeroed();
|
|
libc::sigemptyset(&mut mask);
|
|
libc::sigaddset(&mut mask, libc::SIGINT);
|
|
libc::sigaddset(&mut mask, libc::SIGTERM);
|
|
if libc::sigprocmask(libc::SIG_BLOCK, &mask, std::ptr::null_mut()) < 0 {
|
|
return Err(io::Error::last_os_error());
|
|
}
|
|
|
|
// 2. Create the fd
|
|
let fd = libc::signalfd(-1, &mask, libc::SFD_CLOEXEC | libc::SFD_NONBLOCK);
|
|
if fd < 0 { return Err(io::Error::last_os_error()); }
|
|
|
|
// 3. Register fd on epoll. On EPOLLIN:
|
|
let mut info: signalfd_siginfo = std::mem::zeroed();
|
|
let n = libc::read(fd, &mut info as *mut _ as *mut _, std::mem::size_of::<signalfd_siginfo>());
|
|
if n as usize == std::mem::size_of::<signalfd_siginfo>() {
|
|
match info.ssi_signo as i32 {
|
|
libc::SIGINT | libc::SIGTERM => begin_graceful_shutdown(),
|
|
_ => {}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Key flags
|
|
|
|
| Flag | Meaning |
|
|
| --- | --- |
|
|
| `SFD_CLOEXEC` | Close on exec. Always set. |
|
|
| `SFD_NONBLOCK` | Non-blocking reads. Required when on `epoll`. |
|
|
| `SIG_BLOCK` | Passed to `sigprocmask` to add the set to the current mask. The corresponding `SIG_UNBLOCK` / `SIG_SETMASK` are available if you need them. |
|
|
|
|
## Gotchas
|
|
|
|
- **Blocking the signal with `sigprocmask` is mandatory.** Otherwise the default handler runs and kills the process before the fd ever becomes readable. Block once at boot, never unblock.
|
|
- **Per-thread mask.** `sigprocmask` is per-thread. In a single-threaded runtime that's fine; if you ever spawn threads, use `pthread_sigmask` on each so the main loop gets the signals.
|
|
- **`signalfd_siginfo` is big** (128 bytes). Read into an aligned buffer; partial reads return `EINVAL`.
|
|
- **Doesn't catch `SIGKILL` or `SIGSTOP`.** Nothing does. Those bypass everything.
|
|
- **Child exit notifications (`SIGCHLD`)** work via signalfd but `pidfd` (see [10-pidfd.md](./10-pidfd.md)) is usually the better fit for clean child supervision.
|
|
|
|
## Used by
|
|
|
|
[`04-cutover-remove-tokio-axum.md`](../../done/04-cutover-remove-tokio-axum.md) — replaces `tokio::signal::ctrl_c()` for graceful shutdown. Every subsequent phase inherits this pattern.
|
|
|
|
## v1 port source
|
|
|
|
[`reference/crates/wo-event/src/signalfd.rs`](../../../../.dev/reference/crates/wo-event/src/signalfd.rs) (62 LOC) — `SignalFd::new(&[SIGINT, SIGTERM]) -> SignalFd` with a safe `read_signo()` helper.
|