Struct EfClientState 

#[repr(C)]
pub struct EfClientState {
    pub ctx: *const c_void,
    pub retain: Option<unsafe extern "C" fn(*const c_void)>,
    pub release: Option<unsafe extern "C" fn(*const c_void)>,
}

Client-owned state a library entry point calls back into — frozen by value, forever, and reused verbatim by every domain that needs one (PBO today; CUDA-GL next).

What retain/release govern — and what they do not

They extend the life of the callback channel only. They never transfer ownership of the GL buffer, the CUDA resource, or anything else the context happens to address. Getting this backwards double-frees a GL buffer:

• The producing side’s own destructor stays the sole caller of the real delete_buffer.
• A library that reconstructed operations from this struct treats delete_buffer as a no-op — it borrows the resource, it does not own it.

Ownership at an entry point

An entry point that stores this struct calls retain(ctx) itself and calls release(ctx) exactly once when the object holding it is destroyed. The caller keeps its own count and may drop it at any time after the call returns.

Freezing

This vocabulary declines the struct_size handshake (see the root ARCHITECTURE.md, “Why there is no struct_size handshake”), so a by-value struct grows only by a major bump or a suffixed successor. Freezing one tiny universal struct — rather than one per domain, or one that grows per domain — is what keeps that cost paid once. Its size and offsets are pinned by tests/c/test_layout_goldens.c in edgefirst-tensor-capi and by client_state_layout_is_pinned below.

ctx is opaque to the library: only the producing copy of the code ever dereferences it.

Fields

ctx: *const c_void

Opaque to every caller except this struct’s own function pointers.

retain: Option<unsafe extern "C" fn(*const c_void)>

Add one reference to the callback channel. Never NULL in a valid state; an entry point receiving NULL must fail with EINVAL.

release: Option<unsafe extern "C" fn(*const c_void)>

Drop one reference to the callback channel. Never NULL in a valid state; an entry point receiving NULL must fail with EINVAL.

Trait Implementations

impl Clone for EfClientState

fn clone(&self) -> EfClientState

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for EfClientState