Module rationer 

Rationer — stateful similarity / clustering handle with explicit backend control.

The free-function API (ratio, cluster_canonicals, …) is stateless and rebuilds every per-call resource. That’s fine for one-shot calls, but for callers that issue many clustering jobs in a tight loop (e.g. find-dup-defs runs cluster_canonicals once per same-name group, often a few thousand times per repo) the per-call setup — Metal device handshake, IOPM assertion, thread QoS, GPU warmup dispatch — adds up to seconds. A Rationer constructs that state once at new() and reuses it across every .cluster_canonicals(…) call.

Whether any given call routes through the GPU or stays on CPU is an internal decision; callers don’t pass GPU flags, don’t import the gpu module, and don’t change with feature gates. On systems without Metal (cfg(not(target_os = "macos")) or the gpu feature off), the GPU side is simply absent and every call goes to CPU — same behaviour, same output.

Usage

let r = difflib_fast::Rationer::new();
for group in groups {
    let clusters = r.cluster_canonicals(&group.canonicals, 0.5);
    // ...
}

Pass &Rationer across rayon threads — it’s Send + Sync, designed for shared use from par_iter() chains.

Structs

PreparedRationer

Reusable corpus + SAMs built by Rationer::prepare. Hold this across many ratio_many_idx calls to amortize SAM building and the GPU upload over the lifetime of the string set. Borrowing the Rationer keeps the Metal device and thread pool wiring alive.

Rationer

Handle that owns long-lived clustering resources (Metal device, IOPM power assertion, thread QoS boost). Construct once per process; share &Rationer across rayon workers.

RationerBuilder

Builder for Rationer. Configure once, then .build().

Enums

Concurrency

Backend selection for Rationer similarity work.