Skip to content

API Reference

chumicro_runner

chumicro_runner

Public exports for the chumicro-runner package.

ReentrantTickError

Bases: RuntimeError

Raised when tick() runs while another tick() is in progress.

Runner

Run tasks on a tick-based schedule.

Parameters:

Name Type Description Default
ticks object | None

Optional source (ticks_ms, ticks_diff, ticks_add); default chumicro_timing.

 None
poller object | None

Optional poll object (register/modify/unregister/ipoll); default select.poll adapter.

 None
on_handler_error object | None

Optional (handle, exception) callback invoked when a handler raises.

 None

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

Register a task with the runner.

Parameters:

Name Type Description Default
task object | None

Object with .check(now_ms) and .handle(now_ms); mutually exclusive with handler.

 None
handler object | None

Callable handler(now_ms) fired on schedule; mutually exclusive with task.

 None
period_ms int | None

Optional interval in milliseconds.

 None
start_after_ms int | None

Optional initial delay before the first fire; overrides the first period.

 None
run_count int | None

Optional number of fires before auto-removing; None means unlimited.

 None
preserve_phase bool

When True, fires stay aligned under late ticks; needs period_ms.

 False

Returns:

Type Description
TaskHandle

A TaskHandle for runtime mutation.

add_generator(generator)

Register a generator-driven service with the runner.

Parameters:

Name Type Description Default
generator object

A fresh, not-yet-advanced generator; this method primes it to its first yield.

 required

Returns:

Type Description
GeneratorHandle

A GeneratorHandle carrying .done and .cancel().

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

Register a periodic handler with no check.

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 the first fire.

 None
run_count int | None

Optional number of fires before auto-removing; None means unlimited.

 None
preserve_phase bool

When True, fires stay aligned under late ticks.

 False

Returns:

Type Description
TaskHandle

A TaskHandle for runtime mutation.

tick()

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

Returns:

Type Description
int

The tick timestamp used this cycle.

Raises:

Type Description
ReentrantTickError

A handler called tick() while this tick() was already running.

wait(now_ms)

Idle until a registered socket is ready or the next deadline arrives.

Parameters:

Name Type Description Default
now_ms int

Current tick, typically the value returned by the preceding tick() call.

 required

run_until(predicate=None, *, timeout_ms=None)

Drive tick() and wait() until predicate is truthy.

Parameters:

Name Type Description Default
predicate object | None

A handle (exposes done), a zero-arg callable checked each tick, or None.

 None
timeout_ms int | None

Optional budget (ms), checked between ticks; best-effort under socket waits.

 None

Returns:

Type Description
bool

True when predicate became truthy or the handle finished cleanly, False on timeout.

Raises:

Type Description
BaseException

The handle form re-raises handle.error when the awaited task died.

TaskHandle

Handle returned by Runner.add() or add_periodic().

set_period(period_ms, now_ms=None)

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

Parameters:

Name Type Description Default
period_ms int | None

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

 required
now_ms int | None

Anchor for the next fire, typically the timestamp the enclosing tick() returned; default is a fresh clock read.

 None

remove()

Remove this task from the runner.

chumicro_runner.generators

Suspension helper for generators registered with Runner.add_generator. yield from sleep_until(until_ms) parks the generator until the clock reaches that absolute tick, and the runner keeps serving every other service meanwhile. Registration hands back a GeneratorHandle carrying .done, .error, and .cancel(). Import this module explicitly; a program with no generators never loads it.

chumicro_runner.generators

Suspension helpers for runner-driven generators.

sleep_until suspends a generator registered via Runner.add_generator until an absolute tick arrives.

sleep_until(until_ms)

Suspend the generator until ticks_ms() >= until_ms.

Does no time math of its own: it publishes the deadline and the driver decides when to resume, comparing with the clock it was built on. That keeps a sleep measured in the units of the clock passed to Runner(ticks=...) rather than a second one this module reached for.

Parameters:

Name Type Description Default
until_ms int

Absolute tick value at which to resume, in the driver's units.

 required

Yields:

Type Description
object

A private deadline-wait carrying until_ms.

← Home

Source · \ PyPI · \ Bundle · \ Experimental Bundle