clockblocks.clock.ClockFamilyOptions

class clockblocks.clock.ClockFamilyOptions(timing_policy: float = 0.98, precise_timing: bool = False, spin_guard_duration: float = 0.0005, pool_size: int = 200, prewarm_pool: int = 10, time_backend: TimingBackend | None = None)

Bases: object

Fine-tuning options for a clock family, passed to a master Clock on construction. A master and all its descendants share one scheduler and one thread pool; these knobs configure both.

The live knobs (timing_policy, precise_timing, spin_guard_duration) can be changed after construction via the matching Clock properties; the thread pool knobs are construction-only because the thread pool is built once.

Parameters:

• timing_policy – 0.0 = absolute timing (measure from clock start and catch up as much as possible), 1.0 = relative timing (wait the full delay each time, even when behind), floats in between clamp how far a wait may be compressed/stretched from its nominal length to stay on the absolute schedule. Default value is 0.98 (near-relative: a wait may shave up to 2% of its length per event to catch up).

• precise_timing – When true, use a busy-wait in the immediate run-up to a scheduled action to arrive as precisely as possible. (OS wait is by nature jittery.) Costs one core for at most spin_guard_duration seconds per event. Helps under any timing_policy by tightening whatever that policy optimizes.

• spin_guard_duration – Width (seconds) of the busy-spin guard band used when precise_timing is on. Default 500µs.

• pool_size – Max worker threads in the family’s shared ThreadPoolExecutor, used for every call to fork. Workers are created lazily up to this cap; past it, a forked clock falls back to a plain thread and warns that the pool has run out of threads.

• prewarm_pool – How many pool workers to spin up eagerly at construction, front-loading the (sub-millisecond) thread-creation cost of the first that-many forks. Clamped to pool_size; 0 disables, leaving an idle clock with no threads at all.

Attributes

pool_size
precise_timing
prewarm_pool
spin_guard_duration
time_backend
timing_policy

timing_policy: float = 0.98

precise_timing: bool = False

spin_guard_duration: float = 0.0005

pool_size: int = 200

prewarm_pool: int = 10

time_backend: TimingBackend | None = None