Skip to content

API Reference

Core

chumicro_runner.core

Core tick-runner abstractions for the ChuMicro ecosystem.

Provides two ways to register work with a Runner:

  1. Gate-based — a check function decides whether a handler fires. Register with add(check_function, handler=function) (both callables) or add(obj) where obj has .check(now_ms) -> bool and .handle(now_ms) methods.
  2. Periodic — add_periodic(handler, period_ms): the handler fires every period_ms milliseconds with no check.

All classes are cross-runtime compatible (CPython, MicroPython, CircuitPython).

See plans/decisions/0014-runner-pattern.md for the design rationale.

TaskHandle

Opaque handle returned by Runner.add() or add_periodic().

Provides runtime mutation of a registered task: change its period or remove it from the runner entirely.

Read-only properties expose the current state for inspection and testing.

period_ms property

Return the task period in milliseconds, or None.

run_count property

Return the remaining run count, or None if unlimited.

active property

Return whether the task is still registered.

__init__(entry, runner)

Create a handle wrapping entry owned by runner.

Parameters:

Name Type Description Default
entry _TaskEntry

Internal task record.

 required
runner Runner

Owning runner instance.

 required

set_period(period_ms)

Add, change, or remove the period for this task.

Pass None to remove an existing period (task runs every tick). A non-None value resets the timer so the next fire is period_ms from now.

Parameters:

Name Type Description Default
period_ms int | None

New interval in milliseconds, or None to clear the period.

 required

remove()

Remove this task from the runner.

__repr__()

Return a developer-friendly representation.

Runner

Run tasks on a tick-based schedule.

Captures ticks_ms() once per tick() call and passes the shared timestamp to every due component, ensuring all components see the same moment in time.

Registration paths:

  • add(obj) — obj has .check(now_ms) -> bool and .handle(now_ms). The runner calls .check(); if True, .handle() is queued.
  • add(check_function, handler=function) — callable check gates callable handler.
  • add(handler=function) — handler fires every tick (or per period).
  • add_periodic(handler, period_ms) — fires handler(now_ms) every period_ms milliseconds.

tick() runs in two phases:

  1. Check all entries (period gate, then check gate) and collect due handlers.
  2. Batch-fire all collected handlers.

Period gating uses ticks_diff and ticks_add directly — no Heartbeat objects are created internally.

Parameters:

Name Type Description Default
ticks object | None

Optional tick source (must have ticks_ms, ticks_diff, and ticks_add methods). Defaults to the chumicro_timing module-level functions.

 None

__init__(ticks=None)

Create a runner.

Parameters:

Name Type Description Default
ticks object | None

Optional tick source (must have ticks_ms, ticks_diff, and ticks_add methods). Defaults to the chumicro_timing.ticks module. Constructor injection per Decision 0010; pass FakeTicks from chumicro_timing.testing in tests.

 None

add(task=None, handler=None, period_ms=None, start_after_ms=None, run_count=None)

Register a task with the runner.

Object-based (task only): task must have .check(now_ms) -> bool and .handle(now_ms) methods.

Callable-based (task + handler): task is a callable check_function(now_ms) -> bool that gates handler(now_ms).

Handler-only (handler, no task): handler(now_ms) fires on every tick (or per period if period_ms is set).

Returns a TaskHandle for runtime mutation.

Parameters:

Name Type Description Default
task object | None

Object with .check() and .handle(), or a callable check_function(now_ms) -> bool.

 None
handler object | None

Optional callable handler(now_ms).

 None
period_ms int | None

Optional interval in milliseconds.

 None
start_after_ms int | None

Optional initial delay before the task becomes eligible. Overrides the first period; subsequent fires use period_ms if set.

 None
run_count int | None

Optional number of times the handler may fire before auto-removing. None means unlimited.

 None

add_periodic(handler, period_ms, start_after_ms=None, run_count=None)

Register a periodic handler with no check.

handler(now_ms) is called every period_ms milliseconds. Returns a TaskHandle for runtime mutation.

Parameters:

Name Type Description Default
handler object

Callable handler(now_ms) to fire periodically.

 required
period_ms int

Interval in milliseconds (required).

 required
start_after_ms int | None

Optional initial delay before first fire. Overrides the first period.

 None
run_count int | None

Optional number of times the handler may fire before auto-removing. None means unlimited.

 None

tick()

Capture time, check tasks, then batch-fire handlers.

  1. Check each entry (period gate -> check gate). Collect entries whose handlers should fire.
  2. Batch-fire all collected handlers.
  3. Decrement run counts; auto-remove exhausted entries.

Returns:

Type Description
int

The tick timestamp used this cycle.

← Home

Source · PyPI · Bundle · Experimental Bundle