multimer internals: the dispatcher and the wake sources
How multimer delivers a callback on each host, for anyone changing it or
deciding what a library may do from a callback. The user guide is
multimer.
Shape
Timer ──► one list of armed timers, each with an absolute deadline
│
▼
_dispatch.deliver() runs what is due, re-arms the source
▲
┌─────────────┼─────────────────────────────┐
│ wake source │ idle points │
│ arm(ms) │ sleep_ms, pump, the REPL's │
│ → deliver │ input hook, asleep_ms, the │
│ │ exit-hook loop, repl() │
_dispatch.py owns the list, deliver(), the guards (no nested delivery,
no re-entering a running timer, hold()), the overrun rule, the stats
behind info(), and the portable schedule() queue. It picks a wake source
on the first arm (_select_source) and asks it for one thing: wake me in
N ms. Sources are tiny modules with start(wake), arm(delay_ms),
cancel(), stop(), and two constants, delivery and wakes_blocking.
_hostloop.py decides who owns the main thread after the script body ends
(ambient host loop, an interpreter exit hook, or nothing), unchanged from its
life in appdev except that the exit-hook loop runs while keepalive is
set and a timer is armed. _inputhook.py is the CPython REPL hook.
_repl.py is the in-loop line REPL.
The sources
Source |
Host |
Mechanism |
Delivery |
Wakes a blocked main thread |
|---|---|---|---|---|
|
MicroPython on a board |
one |
bytecode boundary |
yes: the REPL and |
|
unix / macOS CPython and MicroPython |
|
bytecode boundary |
yes: EINTR, then the interrupted call is retried (PEP 475 on CPython, |
|
MicroPython windows |
the |
bytecode boundary |
yes, with the console wait servicing pending callbacks |
|
direct MicroPython WebAssembly |
|
idle (the page loop) |
the loop owns the thread |
|
CPython Windows, Android (and anywhere as a fallback) |
a daemon thread keeps time and calls |
bytecode boundary |
no; |
|
CPython with a running loop |
|
idle (await points) |
the loop owns the thread |
|
CircuitPython, any build with nothing above |
– |
idle points only |
no |
Selection order: MULTIMER_SOURCE if set; wasm when _wasm_bridge
imports; on MicroPython machine, native, signal; on CPython asyncio
when a loop is running or the host is a notebook or PyScript page, then
signal on Linux and macOS, then pending; none last. A source that
fails to start is skipped, and info()["source_error"] says why.
What “between bytecodes” costs
A callback delivered at a bytecode boundary runs in the middle of whatever
the main thread was doing in Python. That is the contract machine.Timer
has always had on a board, and it is why a Python-side audio pump went
wrong: a tick landed between two statements that assumed they ran together.
Two things make it safe:
hold(): a critical section says so, and the dispatcher masks delivery until the block ends.Callbacks never interrupt callbacks: a wake that arrives while
deliver()is running is answered when it returns. So a library’s timer callback sees the library’s own state whole, as long as the library’s main-line code useshold()around its critical sections.
The old layer’s fragility came from the delivery paths: librt ran the
whole callback inside the signal handler on MicroPython (heap locked; hence
the MemoryError guards), sdl2 ran it on SDL’s thread (which Android’s
GLES refused), and threading on MicroPython let micropython.schedule
drain on the worker. None of those paths exists any more.
The overrun rule
After a callback ends, its next slot is due += period. If that slot has
already passed but the pass took no longer than a period, the callback only
started late, behind another one: the grid is stepped past now, each skipped
slot counting in missed, so a late timer never bursts to catch up.
A pass longer than its period has lost its grid, and where the next one goes
depends on whether the program’s own code may want the thread. While the
main thread waits inside multimer, it can’t: the next pass is due the moment
this one ends. The waits that count are run_until, the exit-hook loop,
CPython’s input hook and repl() waiting for input, and a sleep_ms while
more of it is left than the pause below would last, so running back to back
never makes the sleep later than the pause would have. Anywhere else the
next pass waits min(took, yield_cap) from the end of this one. That pause
is the LVGL frame gate of lvgl-bindings#15 and its cap from #19, applied to
every timer: a slow pass halves its own rate rather than taking the thread,
and a pass much longer than a period does not idle the thread for as long
again. yield_cap = 0 waives the pause everywhere, which leaves the
program’s own code about a millisecond between passes.
A timer that skipped its pause remembers it. When a wait returns to the program’s code (the predicate came true, a key or a line arrived), it takes the pause from the end of its last pass, so the code the wait returns to has the thread first.
A delivery is one round: every due timer fires at most once in it, earliest deadline first. A timer due again the moment it returns waits for the next delivery, so other due timers get a turn between its passes and a wait checks its condition between them.
A board’s own REPL is outside multimer, but firmware with
micropython.repl_idle_ms() says how long it has waited for a new command:
-1 while one runs, otherwise the milliseconds since the prompt came back or
input last arrived. A WebREPL file transfer counts as input, though it never
reaches the REPL as characters. Once that reaches 500 ms, a few Wi-Fi round
trips and longer than the gaps inside a tool’s burst of commands, the REPL
counts as a wait like the ones above. Input that comes before the next pass
takes the pause back, as a returning wait does: the pass checks the REPL
again when it comes due.
In an asyncio or browser loop, at the REPL of firmware without that call, or
in a program’s own loop that calls pump(), multimer can’t tell idle from
busy, so the pause applies.
schedule()
On MicroPython it is micropython.schedule. Elsewhere the call is queued
and the source is asked to wake now, so on a bytecode host it runs between
the caller’s next two bytecodes, and on an idle host at the next idle
point. A hold() masks scheduled work too. The queue is locked for callers
on other threads.
The input hook
readline calls PyOS_InputHook about every 100 ms while idle and after each
keystroke; Python 3.13’s _pyrepl calls it from its own wait loop on the
Unix and the Windows console. _inputhook.py waits on stdin itself
inside the hook, delivering as deadlines pass and returning the moment a key
arrives (select on Unix, WaitForSingleObject on the console handle on
Windows), so delivery at the prompt is as punctual as anywhere. The hook is
installed only when the slot is empty (matplotlib and IPython own it
otherwise) and never in a notebook.
The host loop
Strategy |
When |
What |
|---|---|---|
|
a browser page, a notebook, a MicroPython board’s REPL, |
the host’s loop outlives the script; register teardown only |
|
script mode on CPython, MicroPython, CircuitPython |
an exit hook takes the main thread after the last line and delivers until |
|
|
the program blocks itself ( |
A script that crashed does not enter the loop (the crash guard). On CircuitPython boards the loop drains the serial ring each pass, so Ctrl-C still means stop.