#Performance & tuning guide (v1, best-effort)

This is best-effort guidance for getting predictable performance out of IndexBus v1.

Normative behavior is defined by:

• ../spec/v1-semantics.md
• ../spec/v1-failure-lifecycle.md

#Rustdoc entry points

For the API-level surfaces behind tuning decisions, start with:

• indexbus_route
• indexbus_wake
• indexbus_blocking
• indexbus_platform_ops

#Router loop tuning

#Batching

• Increase batch size to improve throughput (amortize per-message overhead).
• Decrease batch size to reduce latency under light load.

Watch:

• batches/sec, batch_avg, batch_max
• tail latency in consumers

#Wait strategy

• Busy spin yields best tail latency at higher CPU cost.
• Backoff reduces CPU but increases wakeup latency.
• Wake-backed waits reduce idle CPU when wake sections are available and used.

#Credits and overload policy

• credit_max bounds consumer lag.
• Drop preserves router throughput but loses data.
• Park preserves data but can stall routing.
• Detach prevents a persistently slow consumer from dominating behavior (router-local state).

#CPU placement and isolation

• Prefer pinning router and critical consumers to dedicated cores.
• Avoid sharing hot-path threads with noisy background work.
• Consider one router per region and (in extreme cases) per NUMA node.

#Memory considerations

• Use mlockall / memlock where appropriate to avoid paging.
• Huge pages can help in some workloads but must be tested end-to-end.
• Ensure SHM files are on a suitable filesystem and have correct permissions.

#Diagnosing bottlenecks

• Use ./v1-triage.md first.
• Use ./router-counters.md to interpret counters.
• If drops occur, treat them as explicit overload: reduce offered load or scale consumers.

#Anti-patterns

• Expecting fairness guarantees in work-queue selection.
• Treating best-effort drop attribution as exact.
• Assuming blocking/wake changes correctness (it only changes waiting behavior).