Skip to content
Librux Runtime Kernel for Robotics development
Librux Runtime Kernel for Robotics development

    Timing Benchmarks

    Timing benchmark scenarios live under benchmarks/timing.

    They focus on execution scheduling semantics, not raw transport mechanics.

    Public Installed-User Flow

    Assume the normal public setup is already complete.

    1. install Librux under /opt/librux
    2. source /opt/librux/env.sh
    3. run benchmark commands from /opt/librux

    If you do not already have a control backend process running, these benchmark runners will start the installed control backend automatically. The equivalent manual development command is librux control --config "$LIBRUX_PREFIX/config.yaml" after sourcing /opt/librux/env.sh.

    Run only one timing benchmark at a time on a host. Timing scenarios share the same local control backend ports and should be treated as isolated measurement runs.

    JSON benchmark reports include a top-level clock_status copied from the local control backend while the run is active. Use that object, not only the per-process compact clock snapshot, when validating correction_*, threshold_kind, domain_compatible, domain_reason, and upstream_* fields.

    Core Idea

    Timing is metadata layered onto runtime requests. The public mental model is this.

    request + timing metadata
  -> runtime normalization
  -> execute_at_sync_ns
  -> server or gateway scheduling

    In other words, timing is not a separate transport. It augments Control, Procedure, and Operation requests.

    See Federation Time Model and Communication Surfaces.

    Coverage

    Scenario Purpose Languages
    timing/control timed typed Control request/response Python, C++
    timing/service timed bounded Procedure side-effect request Python runner, C++ subsystem pair
    timing/action timed Operation start semantics Python runner, C++ subsystem pair

    All timing benchmark scenarios follow the same Subsystem -> declare -> register -> initialize/start pattern described in Cleaner Robot Tutorial.

    The installed and documented benchmark surfaces are Python and C++.

    Reference Results

    The timing reference is a functional and latency-scale record from Ubuntu installed-user validation. It is retained as a timing-behavior reference and not as a universal latency acceptance claim. Refresh this table whenever the timed scheduler or Procedure/Operation dispatch path changes.

    Primary evidence.

    • accepted installed-user timing reports under reports/testing
    Scenario Condition Reference result
    Timed Exchange Python/Python, 20 samples, 2 ms period controller avg 525.008 us, failures/dropped 0/0
    Timed Procedure Python, 20 samples, 2 ms period client avg 995.708 us, server avg 850.716 us, failures/dropped 0/0
    Timed Operation Python, 20 samples, 2 ms period client avg 401.745 us, server avg 123.154 us, failures/dropped 0/0
    Timing gates installed validation Operation/Procedure completed with warnings=[] and dropped 0

    Timed Exchange

    Path - benchmarks/timing/control

    Timed Exchange demonstrates typed request/response payloads plus timed request metadata.

    Common conceptual fields.

    • request_type
    • response_type
    • timing
    • execute_after_ns
    • timing_support

    Recommended benchmark entrypoint.

    python3 benchmarks/timing/control/run_benchmark.py --controller-language python --gateway-language python --count 10 --warmup 2 --period-us 10000 --execute-after-ns 0

    For Control packet transport profiling, use the C++ pair with --payload-size. That mode sends an echoed raw timed payload instead of a typed JSON payload, so payload-size sweeps measure the transport path more directly.

    python3 benchmarks/timing/control/run_benchmark.py --controller-language cpp --gateway-language cpp --payload-size 4096 --count 1000 --warmup 100 --period-us 1000 --execute-after-ns 0

    For sandbox matrix runs, combine --timed-control with --timed-control-payloads.

    python3 tools/qa/run_comms_matrix.py --timed-control --timed-control-payloads 8,1024,4096 --counts 1000 --period-us 1000

    The default late_policy=execute_immediately path treats executed_late as a measured late execution, not as a hard controller failure. The report keeps those samples and surfaces the late counts in the benchmark extra fields.

    If you want deadline misses to fail the scenario instead of being recorded as accepted late executions, run with --late-policy drop or --late-policy reject.

    Timed Procedure

    Path - benchmarks/timing/service

    Timed Procedure demonstrates a side-effect request on the normal Procedure surface, with timing metadata included in the call.

    Recommended benchmark entrypoint.

    python3 benchmarks/timing/service/run_benchmark.py --count 10 --warmup 2 --period-us 10000

    The Procedure runner writes top-level result, warnings, and summary fields. Add --fail-on-warning when client/server drops, failures, or missing samples should fail CI after the report is written.

    Timed Operation

    Path - benchmarks/timing/action

    Timed Operation demonstrates operation start semantics with timing metadata included in the normal operation request.

    Recommended benchmark entrypoint.

    python3 benchmarks/timing/action/run_benchmark.py --count 10 --warmup 2 --period-us 10000

    Add --fail-on-warning when the run is used as a CI or release gate. The runner writes the benchmark report, then returns a nonzero exit code if the report contains client/server failure or drop warnings.

    Lower-Level Subsystem Pairs

    Each timing scenario also exposes direct python/ and cpp/ server/client or gateway/controller pairs. Use those only when you want to inspect subsystem behavior manually. For normal public validation or measurement runs, start with the run_benchmark.py entrypoints above.