Repository navigation
Stoic 0.9.1
Pre-releaseStoic 0.9.1 adds StoicProcess, one way to run other programs that cleans up after itself, and Inactivity, which notices work going quiet without counting a sleeping Mac as stuck.
0.9.0 was tagged but not released: its quietSpells() could miss a quiet spell when a poke landed between its check and its wait. Anyone on 0.9.0 should move to 0.9.1.
StoicProcess: child processes (design/33)
A new library: ChildProcess.run runs a program to its end under a deadline, and ChildProcess.start holds one open. macOS only. It compiles to nothing elsewhere, as StoicXPC does.
- Every child gets a process group of its own, and a stop ends the whole group. A stop sends
SIGTERMto the group, and to any descendant that left it, thenSIGKILLafter the grace. It is shielded from the caller's cancellation and bounded (stopGrace3 s, thenkillWait5 s). A released handle stops its child (process.abandoned). - A crash no longer leaves children running. A
ProcessLedgerrecords owned children. At the next launch,reapOrphans()stops what the crashed run left behind. No signal goes to a pid that may have been reused: a child is known by its pid and its start time, and a pid whose start time no longer matches is left alone. - Output is read only as it is asked for. Reads use kqueue readiness, in chunks of at most 64 KB, with nothing read ahead, so a child whose output nobody reads waits on the pipe and memory never grows. The output ends at end of file, or
drainGraceafter the child when something it started still holds the pipe. Every line is read before the exit is reported. - Input never blocks the sender.
sendqueues in order, each write whole, up toinputCapacity(64 MiB), and throwsinputFullpast it. A child that has gone isEPIPE, never aSIGPIPEthat ends the app. - Why.
Foundation.Processanswers none of this.terminate()reaches only the child, so the shell dies and the server it started keeps the port. The exit can be heard before the last output, a write to a child that stopped reading blocks the writer, and children outlive a crash. Woodsmoke, the pilot, ran programs six ways by hand, and each failure-mode row is one of those bugs or one they were written to avoid. - The cost. The environment is given whole, with no implicit inheritance (
ProcessEnvironment.currentpasses this process's on), and the program is an absolute path, with noPATHsearch. A piped output must be read, or said to be.discard. Not built yet: a simulated process for deterministic tests, pseudo-terminals, and Linux.
Inactivity: quiet spells on the liveness clock (design/34)
Inactivity(after:label:) is poked at each sign of progress. A watcher waits in untilQuiet(), or hears each quiet spell once through quietSpells() (event inactivity.quiet).
- A Mac that slept is not quiet. It measures on
Ambient.livenessClock, which does not advance during sleep. AlastActivitydate compared withDate()wakes from an hour's sleep and reports every piece of work as stuck an hour. - A poke is cheap. It is a write under a lock, and it never wakes the watcher, which re-reads the last poke when its sleep ends. A poke per line of output costs a lock, not a wake-up.
- Each spell is reported once. The next comes only after a poke and another quiet stretch.
- A poke as the watcher turns is heard (new in 0.9.1). In 0.9.0,
quietSpells()checked whether the spell had been reported under the lock, let go of it, and only then registered to wait for a poke. A poke between the two was counted but woke no one, so work that poked once and went quiet again never had that quiet reported. Raced on real threads, 75 of 2,000 rounds lost the poke. The count is now compared and the waiter registered under one lock.nextPoke()keeps its signature and returns at the first poke made after it was called. design/34 has the failure-mode row, and a test that fails on 0.9.0 claims it. - It is the half of a
Supervisorheartbeat that only notices, for work nothing should restart.
Tests that could hang now fail
0.9.0's release CI run was cancelled at its 90-minute limit. On the three-core runner, aPokeWakesThoseWaitingForOne poked before its waiter had registered, and then waited forever: Task.value does not wake for cancellation, so the test's time limit could not end it. It now pokes until the waiter hears one, bounded, and fails rather than hangs. The SingleFlight priority tests got the same treatment. Their first caller started at .background, which macOS starves while default-priority work fills every core, and their waits ignored cancellation. The first caller now starts at .medium, which is still a real escalation to .high, and each wait ends at the time limit. The compile-fail and lint-stub tests no longer block a cooperative thread while swiftc runs, and a compiler that does not finish fails its test.
The first 0.9.1 release CI run hung on both platforms, and its block-buffered logs could not say where. CI now writes test output line by line, and after six silent minutes it fails the job with the test processes' stacks. The next run named a macOS hang in a settings test that predates 0.9.x. It wrote a fixed file before the watch had reloaded the broken one, so the debounce, correctly, waited for the newer write, and the problem the test waited for never began. The test now waits for the reload first, and every wait in the settings tests ends at the test's time limit. The Linux hang of the first run was not identified: it did not recur in two CI runs or in 30 local runs on four CPUs.
Breaking
None: the API check against 0.8.1 reports no breaking change in any library. StoicProcess and Inactivity are additions.
Still owed
- 0.8.0's compatibility fixtures (design/32), including
Presented, and 0.9.1's own are not recorded yet. They will be recorded from each release's tag. - The
ProcessLedgerfile is read by the next launch, which may be a newer build, so it is a format kept across releases. It is not yet among Stoic's own formats in design/32.