# SPDX-FileCopyrightText: 2024 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""multimer: one Timer, one clock, one dispatcher, on every OmniPython host.
::
import multimer
from multimer import Timer
tim = Timer(-1)
tim.init(mode=Timer.PERIODIC, period=10, callback=on_tick)
sub = multimer.every(33, draw)
multimer.report() # what is running, from the REPL
Callbacks run 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). They never run on another thread and never inside a C call. Importing
this package does nothing to the host; the wake source is chosen when the
first timer is armed. See ``docs/guides/timers.md``.
"""
import sys
from ._asyncio_loader import load_asyncio, loop_running
from ._dispatch import (
Timer,
alive,
defer_while,
hold,
info,
keepalive,
pump,
run_until,
schedule,
sleep_ms,
stop_all,
timers,
)
from ._dispatch import source as _source
from ._ticks import (
monotonic,
run_deadline_hook,
set_deadline_hook,
ticks_add,
ticks_diff,
ticks_less,
ticks_ms,
ticks_us,
)
__version__ = "0.2.0"
[docs]
def every(ms, callback, *, name=None):
"""A PERIODIC `Timer` firing ``callback(timer)`` every *ms*."""
return Timer(-1, mode=Timer.PERIODIC, period=ms, callback=callback, name=name)
[docs]
def after(ms, callback, *, name=None):
"""A ONE_SHOT `Timer` firing ``callback(timer)`` once, after *ms*."""
return Timer(-1, mode=Timer.ONE_SHOT, period=ms, callback=callback, name=name)
[docs]
async def asleep_ms(ms):
"""Coroutine sleep for async code; delivers due timers on hosts without a wake source."""
aio = load_asyncio()
if aio is None:
raise ImportError("asleep_ms needs asyncio")
sleep = getattr(aio, "sleep_ms", None)
if sleep is not None:
await sleep(ms)
else:
await aio.sleep(ms / 1000)
pump()
run_deadline_hook()
[docs]
def strategy():
"""How the program stays alive past the script body: ambient, exit_hook, none, or None."""
from . import _hostloop
return _hostloop.strategy()
[docs]
def repl(namespace=None, prompt=">>> ", tick_ms=10):
"""A line REPL that keeps delivering timers while it reads (hosts with no prompt)."""
from ._repl import repl as _repl
return _repl(namespace, prompt, tick_ms)
[docs]
def report(file=None):
"""Print the dispatcher's state and every live timer, for a person at a prompt."""
out = file if file is not None else sys.stdout
d = info()
out.write(
"multimer on %s: source=%s delivery=%s wakes_blocking=%s strategy=%s\n"
% (d["host"], d["source"], d["delivery"], d["wakes_blocking"], strategy())
)
out.write(
" deliveries=%d wakes=%d max_gap=%d ms errors=%d sched_full=%d held=%d keepalive=%s next=%s ms\n"
% (
d["deliveries"],
d["wakes"],
d["max_gap_ms"],
d["errors"],
d["sched_full"],
d["held"],
d["keepalive"],
d["next_ms"],
)
)
if "source_error" in d:
out.write(" source fell back to none: %s\n" % d["source_error"])
ts = timers()
if not ts:
out.write(" no timers armed\n")
for t in ts:
out.write(" %r due_in=%s ms\n" % (t, t.due_in))
__all__ = [
"Timer",
"after",
"alive",
"asleep_ms",
"defer_while",
"every",
"hold",
"info",
"keepalive",
"loop_running",
"monotonic",
"pump",
"repl",
"report",
"run_deadline_hook",
"run_until",
"schedule",
"set_deadline_hook",
"sleep_ms",
"stop_all",
"strategy",
"ticks_add",
"ticks_diff",
"ticks_less",
"ticks_ms",
"ticks_us",
"timers",
]
_SUBMODULES = ("_dispatch", "_hostloop", "_inputhook", "_repl", "_ticks", "_asyncio_loader")
def __getattr__(name):
if name == "asyncio":
return load_asyncio()
if name == "source":
s = _source()
return None if s is None else s.name
# MicroPython resolves ``from . import _hostloop`` through the package's
# __getattr__ and does not fall back to importing the submodule itself.
if name in _SUBMODULES:
module = __import__(__name__ + "." + name, None, None, (name,))
globals()[name] = module
return module
raise AttributeError("module %r has no attribute %r" % (__name__, name))