multimer
One Timer with machine.Timer’s shape, one clock, and one place that
delivers callbacks, on every interpreter OmniPython runs on. The script ends,
the prompt comes back, and the timers keep firing.
import multimer
from multimer import Timer
def on_tick(tim):
print("tick", tim.fired)
tim = Timer(-1)
tim.init(mode=Timer.PERIODIC, period=500, callback=on_tick) # as on a board
That is the whole program. Run it with -i and you are at >>> with tim
ticking; type multimer.report() to see it. Run it without -i and the
process exits when the script ends, like a daemon thread, unless something
asks it to stay (an appdev.App does, or multimer.keepalive()).
The API
import multimer
from multimer import Timer, every, after, sleep_ms, schedule, hold
sub = every(33, draw) # a PERIODIC Timer, returned
tok = after(500, done) # a ONE_SHOT Timer
sub.deinit() # or sub.cancel(); machine.Timer's spelling
sleep_ms(100) # sleep; due timers are delivered on the way
schedule(fn, arg) # run fn(arg) at the next safe point
with hold(): # nothing is delivered in here
critical_section()
multimer.report() # what is running, from the REPL
Function |
Meaning |
|---|---|
|
|
|
a PERIODIC / ONE_SHOT |
|
sleep, delivering due timers on every host |
|
deliver what is due now; returns ms until the next deadline |
|
|
|
context manager: delivery masked inside, flushed once at exit |
|
keep the process alive past the script’s end while timers are armed |
|
block, delivering, until |
|
what is armed, the dispatcher’s state, both printed for a person |
|
a line REPL that keeps delivering, for hosts with no prompt (CircuitPython) |
|
coroutine sleep for async code |
|
the clock |
|
how the program stays alive: |
A timer knows about itself: period, mode, callback, running,
due_in, fired, missed, late_max (ms), last, error (the last
exception its callback raised), and a settable name for report().
repr(tim) shows them.
MULTIMER_SOURCE=<name> in the environment forces a wake source (below),
for tests. import multimer does nothing to the host; the source is chosen
when the first timer is armed.
What a callback can count on
Every callback is called with the timer as its one argument, so a method
written def step(self): raises TypeError on every tick. multimer prints
that once and then counts the later failures without printing, which looks
like a frozen or black screen with a single traceback above it. Write
def step(self, timer=None). app.every and multimer.every work the same
way.
A callback runs on the main thread, at a safe point: between two bytecodes
where the host can interrupt (a board, a signal, a pending call), otherwise
at the next idle point (sleep_ms, pump(), the REPL waiting for a key, an
await). It never runs on another thread and never inside a C call.
A callback never interrupts another callback. A callback that is still
running when its next slot comes is not re-entered; the slot is skipped and
counted in missed. Deadlines are absolute, so delivery latency never
drifts the schedule. A callback that raises is printed once and keeps its
schedule; the exception is on tim.error. A KeyboardInterrupt (Ctrl-C) or
SystemExit raised in a callback is not caught: it reaches your code or the
REPL, and the timers keep running. Where the callback ran inside the
interpreter’s scheduler (MicroPython) or a C callback, which can’t pass an
exception on, multimer raises it at the main thread’s next idle point
instead: sleep_ms, pump, run_until, or the loop that keeps a script
running after its last line. So sys.exit() from a timer ends the program
the same way on every host. A board’s REPL that is back at its prompt drops
what multimer kept, because the command it was meant for has ended. On
OmniPython firmware, a
Ctrl-C that lands in a callback also stops the code the callback
interrupted, so one press stops a command at the REPL however much of the
time your timers take.
A callback that takes longer than its period runs again as soon as it
returns while your program waits in multimer: in sleep_ms, in run_until,
at CPython’s prompt or in multimer.repl() waiting for input, or in the loop
that keeps a script running after its last line. While your own code runs,
the timer pauses after each pass for as long as the pass took, up to
yield_cap (100 ms by default, per timer), so a slow pass lowers its rate
instead of taking the thread from your code. At a MicroPython board’s own
prompt it runs back to back too once the REPL has waited half a second with
no input, on firmware that has micropython.repl_idle_ms()
(OmniPython firmware
for ESP32 boards); a command, a paste or a WebREPL file transfer
gets the pause while it runs. Other firmware can’t tell a waiting REPL from a
running command, so the pause applies at its prompt; to run a slow timer back
to back there, end the program in run_until or a sleep_ms loop. How the
overrun rule works.
On a board whose REPL is its native USB port (TinyUSB CDC, as on the ESP32-S3 and ESP32-P4), Ctrl-C can’t cut a long callback short: the port reads the key in a scheduled task, which waits for the running callback to return. The program stops as soon as it does. A UART or USB Serial/JTAG console, and unix, raise it inside the callback.
Because the host can interrupt between bytecodes, code that must not be
interrupted says so: with multimer.hold():. Everything that came due is
delivered once at the end of the block.
hard is accepted for machine.Timer parity; every host delivers soft,
which is what hard=False means on a board.
Hosts
The dispatcher is the same everywhere. What differs is the wake source,
the host’s way of getting the main thread’s attention, chosen once when the
first timer is armed and named in report():
Host |
Source |
Delivery |
Idle prompt served? |
|---|---|---|---|
MicroPython on a board |
|
between bytecodes |
yes |
MicroPython unix, macOS |
|
between bytecodes |
yes |
MicroPython windows |
|
between bytecodes |
yes |
MicroPython wasm (direct) |
|
when the VM is idle |
the page loop |
CPython Linux, macOS |
|
between bytecodes |
yes |
CPython Windows, Android |
|
between bytecodes |
yes, through the input hook |
CPython with a running asyncio loop (Jupyter, PyScript) |
|
at await points |
the loop |
CircuitPython |
none |
|
no prompt to serve |
On CPython, multimer also installs a PyOS_InputHook that serves timers
while the REPL waits for a key, on 3.11’s readline and 3.13’s new REPL, on
Unix and Windows. MULTIMER_INPUTHOOK=0 turns it off.
On a host without a wake source, sleep_ms and pump() are the program’s
part of the bargain: a script
that computes without yielding delivers nothing until it yields.
Introspection where there is no prompt
Jupyter: run
multimer.report()in a cell; timers keep firing between cells because the kernel’s loop is the source.A browser page (PyScript, the direct wasm build): the same call from the page’s console or REPL; the page loop is the source.
CircuitPython:
code.pyends withmultimer.repl(). It reads lines from the serial port between deliveries and evaluates them in the script’s namespace, soreport()and the program’s own objects are reachable without stopping it. Ctrl-D returns.A MicroPython board: the script ends, the REPL comes back, and
report()works there like on a desktop.
Async code
Where a host owns an asyncio loop, multimer rides it: nothing to configure.
For your own coroutines use multimer.asleep_ms(ms) (or the loop’s sleep)
and multimer.loop_running() when a library must know whether a loop is up;
get_event_loop() and get_running_loop() are not portable enough for that
test across MicroPython and CircuitPython.
OmniPython integration
appdev.App is built on this: app.every() returns a multimer.Timer, the
device service tick and each display’s refresh are ordinary timers you see in
report(), and an App sets keepalive. display_driver (LVGL) runs LVGL
on one timer that asks LVGL when to come back, and presents from the
display’s frame_clock. Neither needs app.run().