Struct JointConstraintCarrier 

pub struct JointConstraintCarrier { /* private fields */ }

Device-resident buffer set for the joint placement/relation constraint solve. All memory is runtime-backed and xlog-owned; every buffer is shared between the carrier’s working columns and the outward export surface, so both sides observe one allocation identity.

Implementations

impl JointConstraintCarrier

pub fn allocate( device: Arc<CudaDevice>, entities: usize, domain_lanes: usize, candidates: usize, labels: usize, ) -> Result<Self, CarrierError>

Allocate the capacity-bounded carrier buffers through the xlog device runtime: entity sort-domain bitsets, relation candidate scores, constraint slots, and solver outputs.

pub fn allocate_with_max_arity( device: Arc<CudaDevice>, entities: usize, domain_lanes: usize, candidates: usize, labels: usize, max_arity: usize, ) -> Result<Self, CarrierError>

Allocate an arbitrary-arity carrier. Candidate rows are padded to max_arity; the active width of every row lives in its owned arity buffer and is consumed by the solver kernels.

pub fn note_producer_stream( &mut self, external_stream: u64, ) -> Result<(), CarrierError>

Record a producer-completion event on an EXTERNAL stream (a raw CUstream handle on this device — e.g. torch’s current_stream().cuda_stream). The next solve stage waits on every noted event BEFORE launching, so producer writes through exported views order against the solve entirely on device — no host synchronization barrier is involved, which is what keeps the measured region host-interaction-free.

pub fn note_consumer_stream( &mut self, external_stream: u64, ) -> Result<(), CarrierError>

Register an external CUDA stream to consume the next successful solve stage. After the solve work is enqueued, the carrier records one completion event on its internal stream and makes every registered consumer stream wait on that event.

pub fn export_buffer(&self, id: CarrierBufferId) -> CarrierExport

Export one buffer outward while xlog retains ownership. The returned Arc shares the exact allocation the carrier solves on; the binding layer wraps it in a DLPack capsule via CudaColumn::dlpack_xlog_owned, and strict launch recorders keep recording the exported view.

pub fn bind_signatures( &mut self, head_masks: &[u64], tail_masks: &[u64], ) -> Result<(), CarrierError>

Bind the catalog-bound label signature masks, one cold-path upload per session after schema registration. Each mask slice is labels x domain_lanes u64 words.

pub fn bind_role_signatures( &mut self, role_masks: &[u64], ) -> Result<(), CarrierError>

Bind role-indexed catalog signatures in role-major order: max_arity x labels x domain_lanes u64 words.

pub fn solve_label_feasibility( &mut self, abstain_label: u32, fuel: &mut FuelMeter, ) -> Result<(), CarrierError>

Run the existential label-feasibility stage on device through a strict launch recorder. Fuel is charged with one node expansion per (candidate, label) cell BEFORE the launch — beyond fuel the solve refuses typed without touching the device. Results stay device-resident in the outputs (feasible counts) and feasible-sets columns.

pub fn solve_label_map_top2( &mut self, fuel: &mut FuelMeter, ) -> Result<(), CarrierError>

Run the per-candidate exact top-two stage on device, consuming the feasibility stage’s feasible sets — a real produce/consume chain whose cross-stream ordering rides on the recorded launch events, not on host synchronization. Fuel is charged one node expansion per (candidate, label) cell BEFORE the launch.

The results are the exact global max-marginal ONLY for single-candidate components (see crate::joint_solver::ConstraintGraph::decompose); a set ambiguity flag is a typed MAP-ambiguity signal and must never emit as a unique label. Multi-candidate components stay behind the cross-candidate dynamic-programming stage.

pub fn solve_components_exact( &mut self, fuel: &mut FuelMeter, ) -> Result<(), CarrierError>

Discover candidate components from the carrier-owned argument matrix and solve every component exactly on the device. No component membership crosses the host boundary. Components beyond complete-enumeration capacity continue through the device-discovered exact chain DP and then general device branch-and-bound. Topology and arity never select a refusal; only measured fuel exhaustion may refuse (status 3).

pub fn columns(&self) -> impl Iterator<Item = &CudaColumn>

All device columns the carrier owns, in a stable order: domains, scores, constraints, outputs (feasible counts), feasible sets, map results, solve status.

pub fn register_schema( &mut self, catalog_sha: &str, solver_identity: &str, ) -> Result<(), CarrierError>

Bind the carrier session to one catalog anchor and one solver identity (see crate::joint_solver::SOLVER_ABI_IDENTITY). Registration is once-per-session: a second call refuses with the typed CarrierError::SchemaAlreadyRegistered variant carrying both bound identities.

Trait Implementations

impl Drop for JointConstraintCarrier

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.