Skip to content

Strict Constraints

These constraints represent the non-negotiable laws of the Locus codebase. Violations will result in immediate PR rejection.

1. Memory Safety & Allocations

Locus achieves its latency targets by strictly avoiding the system allocator (malloc/free) in the hot loop. * Hot Loop (detect()): * ❌ Forbidden: Vec::new(), Box::new(), HashMap::new(), or any implicit heap allocations. * ✅ Required: Use the bumpalo::Bump arena for all ephemeral per-frame data. * ✅ Required: Adhere to the DetectionBatch (SoA) Contract to ensure zero-allocation performance and cache efficiency. * ✅ Allowed: Stack-allocated structures like SmallVec, arrayvec, or fixed-size arrays [T; N].

2. FFI & Zero-Copy Boundaries

The Rust-Python boundary must be invisible to performance. * Image Data: * ❌ Forbidden: Copying or cloning NumPy arrays into Rust Vec<u8>. * ❌ Forbidden: Passing non-contiguous views (stride_x != 1) to high-performance detection methods. * ✅ Required: Use PyReadonlyArray2<u8> to leverage the Python Buffer Protocol. Validate strides early and once. * ✅ Required: Throw a ValueError for non-contiguous arrays to force users to use .ascontiguousarray(). * ✅ Required: Image buffers used with SIMD-vectorized kernels (e.g., AVX2 gather) MUST have at least 3 bytes of padding at the end to prevent out-of-bounds reads during 32-bit pixel fetching.

3. Unsafe Rust

  • ❌ Forbidden: Naked unsafe blocks.
  • ✅ Required: Every unsafe block must be immediately preceded by a // SAFETY: comment that rigorously justifies why the invariant holds (e.g., "Strides were checked at the FFI boundary").

4. Error Handling

  • ❌ Forbidden: unwrap() or expect() in library code. (Enforced via #![deny(clippy::unwrap_used)]).
  • ✅ Required: Propagate errors gracefully using Result<T, E> and thiserror for structured error definitions.

5. Performance Reporting & Benchmarking

To ensure reproducibility and scientific integrity, all benchmark reports must be grounded in verified system state. * ❌ Forbidden: Placeholder or assumed hardware specifications (e.g., "Intel CPU" without verification). * ✅ Required: Every performance or accuracy report MUST include verified hardware metadata obtained via system tools (e.g., lscpu, /proc/cpuinfo) during the same session the benchmark was executed. * ✅ Required: State the build profile (--release), thread count, and environment variables (e.g., RAYON_NUM_THREADS) used during the run.