Skip to content

API Reference

chumicro_timing.ticks

Wrap-safe millisecond arithmetic. ticks_ms() reads the runtime's own counter, and ticks_diff and ticks_add compare and advance those readings correctly across a rollover.

chumicro_timing.ticks

Cross-runtime wrap-safe millisecond ticks and signed-difference math; values wrap every ~6.2 days.

ticks_ms()

Returns the current tick in [0, TICKS_MAX]; compare with ticks_diff, not subtraction.

ticks_add(ticks, delta)

Returns ticks advanced by delta within the wrap-safe range.

Raises:

Type Description
OverflowError

When delta reaches half a period (~3.1 days) in either direction.

ticks_diff(end, start)

Returns the signed millisecond distance from start to end.

Returns:

Type Description
int

Signed value in [-TICKS_HALFPERIOD, TICKS_HALFPERIOD); gaps over ~3.1 days
int

(half the wrap period) alias to the wrong sign.

chumicro_timing.deadline

The value objects re-exported from chumicro_timing: Deadline (a single armed timeout) and Rate (a drift-free periodic cadence).

chumicro_timing.deadline

Value objects built on the tick functions: Deadline and Rate.

Deadline

A single armed deadline: period_ms from the now_ms it was built at.

expired(now_ms)

Return True once now_ms has reached or passed the due tick.

remaining(now_ms)

Return milliseconds until due, clamped at 0 once past the due tick.

reset(now_ms)

Re-arm the same period_ms from now_ms.

Rate

Fires at most once per period_ms, drift-free and phase-aligned.

due(now_ms)

Return True once the period has elapsed, re-phasing to the next fire.

reset(now_ms)

Re-anchor the cadence so the next fire lands one period_ms after now_ms.

chumicro_timing.waits

The completion-wait vocabulary for generator flows: Signal connects a callback-style service to a generator task, and wait_for suspends the generator until the signal is set or its deadline passes. Import it explicitly from chumicro_timing.waits.

chumicro_timing.waits

Completion-wait vocabulary: Signal and wait_for.

Signal

One-slot completion token connecting callback-style services to generator tasks.

next_deadline(now_ms)

Absolute tick deadline gating the wait, or None for indefinite.

set(value=None)

Complete the signal, storing value for the waiting generator.

clear()

Re-arm for reuse: drop the stored value and the set flag.

ready(now_ms)

Return whether the waiting generator should resume: True once set.

A bounded wait also has to resume when its deadline lands so wait_for can raise ETIMEDOUT. That compare belongs to the driver, which owns the clock, and it reads the deadline from next_deadline; answering it here would measure the timeout with this module's ticks rather than the driver's.

wait_for(signal, *, deadline_ms=None)

Suspend until signal is set; return the value it carries.

Parameters:

Name Type Description Default
signal Signal

Signal to wait on; not cleared on return.

 required
deadline_ms int | None

Absolute ticks_ms deadline, or None to wait indefinitely.

 None

Yields:

Type Description
object

signal itself on each suspension.

Returns:

Type Description
object

The value passed to signal.set.

Raises:

Type Description
OSError

ETIMEDOUT when deadline_ms elapses before the signal is set.

← Home

Source · \ PyPI · \ Bundle · \ Experimental Bundle