Skip to main content

FfiBindData

Struct FfiBindData 

Source
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 — boxes T via Box::into_raw, registers the pointer and the destroy destructor with DuckDB.
  • DuckDB calls destroy when the bound plan is discarded, which drops the Box<T>. That is not necessarily the end of the first query: a prepared statement binds once and reuses the bind data for every EXECUTE, so treat it as immutable after bind and build per-execution state in init.
  • Retrieval methods borrow the T for the duration of the callback.

Implementations§

Source§

impl<T: 'static> FfiBindData<T>

Source

pub unsafe fn set(info: duckdb_bind_info, data: T)
where T: Send + Sync,

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
  • info must be a valid duckdb_bind_info provided by DuckDB in 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 (through BindInfo::as_raw) is the first of two.
Source

pub 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.

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.

Source

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
  • info must be a valid duckdb_init_info.
  • T must be the type passed to set for this function.
  • No mutable reference to the same data must exist simultaneously.
  • The returned reference is valid for the duration of the init callback.
Source

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
  • info must be a valid duckdb_function_info from a scan callback.
  • T must be the type passed to set for this function.
  • No mutable reference to the same data must exist simultaneously.
  • The returned reference is valid for the duration of the scan callback.
Source

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
  • ptr must have been allocated by set via Box::into_raw.
  • Must be called exactly once (DuckDB guarantees this for bind data destroyers).

Trait Implementations§

Source§

impl<T: 'static> Debug for FfiBindData<T>

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<T> Freeze for FfiBindData<T>

§

impl<T> RefUnwindSafe for FfiBindData<T>
where T: RefUnwindSafe,

§

impl<T> Send for FfiBindData<T>
where T: Send,

§

impl<T> Sync for FfiBindData<T>
where T: Sync,

§

impl<T> Unpin for FfiBindData<T>
where T: Unpin,

§

impl<T> UnsafeUnpin for FfiBindData<T>

§

impl<T> UnwindSafe for FfiBindData<T>
where T: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.