Guide

This section describes the TimeRun API: its concepts, parameters, and behavior. Use it after the Quickstart for a complete picture of blocks, functions, metadata, callbacks, and sync/async and generator support.

You can also use it as a lookup while working with the library.

For applied patterns (e.g. attaching a request id in on_start, exporting to OpenTelemetry), see the Cookbook.

Using the Timer

• Timer overview — How wall and CPU time are recorded, constructor parameters, context manager and decorator usage, and callbacks.
• Measure a block — Using with Timer() and async with; one measurement per block; nested, sequential, and multi-threaded use; exceptions and invalid use.
• Measure function calls — Using @Timer() with sync/async functions and generators; the measurements deque and maxlen; thread safety.
• Metadata — Supplying and copying metadata; per-measurement mutation; isolation between runs.
• Callbacks — on_start and on_end: when they are invoked, what they receive, and the synchronous-only contract.

Core types

• TimeSpan — Immutable time interval: attributes, timedelta, comparison, and validation.
• Measurement — A single run’s result: wall_time, cpu_time, and metadata.