pub struct FfiBindData<T: 'static> { /* private fields */ }Expand description
Type-safe bind data wrapper for DuckDB table functions.
FfiBindData<T> boxes a T on the heap during bind and provides
safe access in subsequent phases. DuckDB owns the allocation lifetime
and calls the provided destroy callback when the query is done.
§Memory model
set— boxesTviaBox::into_raw, registers the pointer and thedestroydestructor withDuckDB.DuckDBcallsdestroywhen the bound plan is discarded, which drops theBox<T>. That is not necessarily the end of the first query: a prepared statement binds once and reuses the bind data for everyEXECUTE, so treat it as immutable after bind and build per-execution state ininit.- Retrieval methods borrow the
Tfor the duration of the callback.
Implementations§
Source§impl<T: 'static> FfiBindData<T>
impl<T: 'static> FfiBindData<T>
Sourcepub unsafe fn set(info: duckdb_bind_info, data: T)
pub unsafe fn set(info: duckdb_bind_info, data: T)
Stores data as the bind data for this table function invocation.
Call this inside your bind callback to save configuration that will
be accessed in init and scan callbacks.
T must be Send + Sync. Bind data outlives the bind callback: a
prepared statement keeps it across executions, every init reads it,
and with InitInfo::set_max_threads
above 1 several scan threads read it at once. It is dropped on whichever
thread tears the plan down.
§Safety
infomust be a validduckdb_bind_infoprovided byDuckDBin a bind callback.- Must be called at most once per bind invocation; calling twice leaks the first allocation.
The bind of a typed table function
(
TableFunctionBuilder::with_state) sets the bind data itself after the closure returns, so a call from the closure (throughBindInfo::as_raw) is the first of two.
Sourcepub const fn get_from_bind<'a>(info: duckdb_bind_info) -> Option<&'a T>
👎Deprecated since 0.16.0: always returns None — DuckDB has no duckdb_bind_get_bind_data. Keep the value in a local during bind; use get_from_init / get_from_function afterwards.
pub const fn get_from_bind<'a>(info: duckdb_bind_info) -> Option<&'a T>
always returns None — DuckDB has no duckdb_bind_get_bind_data. Keep the value in a local during bind; use get_from_init / get_from_function afterwards.
Always returns None.
§Deprecated
This method cannot work and never could. DuckDB’s C API has no
duckdb_bind_get_bind_data: the bind info exposes
duckdb_bind_get_extra_info, duckdb_bind_get_parameter,
duckdb_bind_get_named_parameter and the set_* calls, and nothing that
reads back what duckdb_bind_set_bind_data stored. Bind data is
write-only during bind and readable from init and scan onwards.
Because it is safe and returns Option, a caller writing the natural
if let Some(cfg) = get_from_bind(info) silently takes the wrong branch
forever. Keep the value in a local instead, and use
get_from_init /
get_from_function in the later phases.
Sourcepub unsafe fn get_from_init<'a>(info: duckdb_init_info) -> Option<&'a T>
pub unsafe fn get_from_init<'a>(info: duckdb_init_info) -> Option<&'a T>
Retrieves a shared reference to the bind data from a global init callback.
Returns None if no bind data was set or the pointer is null.
§Safety
infomust be a validduckdb_init_info.Tmust be the type passed tosetfor this function.- No mutable reference to the same data must exist simultaneously.
- The returned reference is valid for the duration of the init callback.
Sourcepub unsafe fn get_from_function<'a>(info: duckdb_function_info) -> Option<&'a T>
pub unsafe fn get_from_function<'a>(info: duckdb_function_info) -> Option<&'a T>
Retrieves a shared reference to the bind data from a scan callback.
Returns None if no bind data was set or the pointer is null.
§Safety
infomust be a validduckdb_function_infofrom a scan callback.Tmust be the type passed tosetfor this function.- No mutable reference to the same data must exist simultaneously.
- The returned reference is valid for the duration of the scan callback.
Sourcepub unsafe extern "C" fn destroy(ptr: *mut c_void)
pub unsafe extern "C" fn destroy(ptr: *mut c_void)
The destroy callback passed to duckdb_bind_set_bind_data.
DuckDB calls this when the query is complete. It drops the Box<T>.
§Pitfall L3: T::drop is user code
DuckDB invokes this through an extern "C" function pointer with no
error channel, and Rust 1.81+ turns an unwind across extern "C" into a
process abort. The drop therefore runs under
catch_ffi_panic; a panicking
Drop impl costs the diagnostic, not the session.
§Safety
ptrmust have been allocated bysetviaBox::into_raw.- Must be called exactly once (
DuckDBguarantees this for bind data destroyers).