The Critical Plumbing: Re-exporting C++ Mutex Functions Through Bellperson's Groth16 Module

Message Overview

Now re-export from bellperson's groth16 mod:

>

[edit] /home/theuser/curio/extern/bellperson/src/groth16/mod.rs Edit applied successfully.

This brief message — a single edit operation with no additional commentary — is the culmination of a complex chain of reasoning about Rust module visibility, FFI boundaries, and dependency graphs. On its surface, it appears trivial: a developer adding a pub use re-export in a module file. But this edit is the final link in a chain that threads a C++ std::mutex pointer from a CUDA kernel file, through three Rust crates, into the engine that orchestrates GPU proof generation. Without this re-export, the entire Phase 8 dual-worker GPU interlock architecture would fail to compile.

The Problem: A Dependency Graph Impasse

The subject message sits at the end of a multi-step plumbing operation that began when the assistant realized a fundamental architectural constraint: the proving engine in cuzk-core cannot directly call functions from supraseal-c2, the Rust binding crate for the CUDA C++ proof generation library. The dependency chain is strictly layered: supraseal-c2 → bellperson → cuzk-core. The engine imports crate::pipeline::gpu_prove() and uses types from bellperson::groth16, but it has no direct access to the supraseal_c2 namespace.

This constraint emerged during Step 5 of the Phase 8 implementation ([msg 2181]), when the assistant was designing the engine changes. The assistant initially considered having the engine call supraseal_c2::alloc_gpu_mutex() directly, then realized: "The engine can't directly access supraseal_c2 — it needs to go through bellperson or pipeline" ([msg 2202]). This realization triggered a search: the assistant ran grep for supraseal_c2 across the codebase to understand existing access patterns, finding five matches in bellperson files but none in the engine.

The solution was to add wrapper functions in bellperson's supraseal module and re-export them through bellperson's public API. Message [msg 2203] added the wrappers:

// In bellperson/src/groth16/prover/supraseal.rs
pub fn alloc_gpu_mutex() -> *mut std::ffi::c_void {
    supraseal_c2::alloc_gpu_mutex()
}

pub fn free_gpu_mutex(ptr: *mut std::ffi::c_void) {
    supraseal_c2::free_gpu_mutex(ptr)
}

The subject message (msg 2204) completes this plumbing by re-exporting these functions from bellperson/src/groth16/mod.rs, making them available as bellperson::groth16::alloc_gpu_mutex and bellperson::groth16::free_gpu_mutex — accessible from the engine.

The Reasoning Process: Tracing the Assistant's Thinking

The assistant's thinking process is visible across the preceding messages. When the build failed in [msg 2201], the assistant didn't just fix the compiler error mechanically. Instead, it traced the dependency chain backward, asking: Why can't the engine call supraseal_c2? The answer required understanding the crate graph:

• cuzk-daemon depends on cuzk-core (the engine)
• cuzk-core depends on bellperson (the Groth16 library)
• bellperson depends on supraseal-c2 (the C++ FFI bindings)
• cuzk-core does not depend on supraseal-c2 directly This is a deliberate architectural layering. The engine should not need to know about the low-level C++ FFI details. It should interact with the proving system through bellperson's abstractions. But the Phase 8 design introduced a new requirement: the engine needs to allocate C++ std::mutex objects — one per GPU — and pass their raw pointers through the call chain to the CUDA kernel. The assistant's reasoning shows it considering alternatives. In [msg 2181], it initially thought about using a Rust std::sync::Mutex<()> and passing its pointer, but then realized: "Wait — I need to reconsider. The C++ side expects a std::mutex* (C++ std::mutex). A Rust std::sync::Mutex<()> is NOT the same thing." This cross-language type safety concern led to the decision to add C++ helper functions (create_gpu_mutex/destroy_gpu_mutex) in the .cu file, then expose them through FFI.

Assumptions Made

The assistant made several assumptions in this message and the surrounding work:

That the re-export path is correct. The assumption that bellperson::groth16::alloc_gpu_mutex would be accessible from cuzk-core depends on the existing dependency graph and the pub use chain being complete. The assistant verified this by checking existing access patterns ([msg 2202]), finding that bellperson already re-exports supraseal_c2::SRS through its supraseal_params.rs module.

That the C++ mutex pointer is opaque to Rust. By using *mut std::ffi::c_void as the type for the mutex pointer, the assistant assumes that Rust code never needs to inspect or manipulate the mutex — it only passes it through to the C++ layer. This is a safe assumption given the design: the mutex is locked and unlocked entirely within C++ code.

That the SendableGpuMutex wrapper provides the right safety guarantees. The assistant created a SendableGpuMutex struct (visible in [msg 2182]) wrapping the raw pointer, implementing Send and Sync to allow sharing across threads. This assumes that the underlying C++ mutex is safe to use from multiple Rust threads — a reasonable assumption since std::mutex is designed for multi-threaded access.

Input Knowledge Required

To understand this message, one needs knowledge of:

Rust module and visibility system. The pub use re-export mechanism is essential — without it, the functions would be private to the prover::supraseal submodule and inaccessible from cuzk-core.

FFI and cross-language type handling. The distinction between Rust's std::sync::Mutex and C++'s std::mutex is critical. They have different memory layouts and cannot be used interchangeably.

The crate dependency graph. Understanding that cuzk-core → bellperson → supraseal-c2 forms a strict chain, and that the engine cannot bypass bellperson to call supraseal-c2 directly.

The Phase 8 architecture. The dual-worker GPU interlock requires two GPU workers per device sharing a single C++ mutex. One worker runs CPU preprocessing while the other holds the mutex for CUDA kernel execution. This interleaving pattern is the core innovation of Phase 8.

Output Knowledge Created

This message creates:

A public API surface — bellperson::groth16::alloc_gpu_mutex() and bellperson::groth16::free_gpu_mutex() become available to any crate that depends on bellperson, including cuzk-core.

A completed FFI plumbing chain — the mutex pointer can now flow: C++ .cu file → supraseal-c2 FFI → bellperson wrappers → engine worker spawn code → pipeline::gpu_prove() → bellperson's prove_from_assignments → supraseal_c2::generate_groth16_proof → C++ generate_groth16_proofs_c. Every link in this chain is now connected.

A verified compilation path — after this edit, the next build attempt ([msg 2205]) succeeds, confirming the re-export resolves the visibility issue.

Broader Significance

This message exemplifies a recurring pattern in systems engineering: the most architecturally significant changes often manifest as the smallest diffs. A single line adding pub use is the difference between a system that compiles and one that doesn't. The re-export is the keystone in an arch of seven files and ~195 lines of changes spanning C++, Rust FFI, and application logic.

The Phase 8 dual-worker GPU interlock ultimately achieved a 13–17% throughput improvement and 100% GPU utilization ([chunk 24.0]). But none of that would be possible without the plumbing work that threads the mutex pointer through the entire dependency chain. This message, for all its brevity, represents the moment the architecture became coherent — when the last visibility gap was closed and the cross-crate FFI path was complete.

It also demonstrates a disciplined approach to dependency management. Rather than adding a direct dependency on supraseal-c2 from cuzk-core (which would violate the architectural layering), the assistant chose to extend the existing abstraction boundary through bellperson. This preserves the separation of concerns: the engine works with Groth16 proofs at a high level, while the C++ FFI details remain encapsulated in the lowest layer of the dependency graph.