Skip to main content

ScalarBindData

Struct ScalarBindData 

Source
pub struct ScalarBindData<T: Send + Sync + 'static> { /* private fields */ }
Expand description

Type-safe bind data for a DuckDB scalar function.

Set once in the bind callback; read in init and in every execution. DuckDB owns the allocation and frees it through a generated, panic-safe destructor when the bound function is discarded.

§Why T: Clone + Send + Sync

  • Send + Sync: every thread executing the query reads the same value concurrently (see the module docs).
  • Clone (on set): DuckDB copies the bound expression whenever the optimizer duplicates it — filter pushdown through a projection does — and a copy made without a copy callback has no bind data at all. set registers a generated copy callback that clones T.

For data that is expensive or impossible to clone, store an Arc<T>: cloning it is a reference-count bump, and every copy then shares one value.

§Bind data must be a function of the call’s arguments

DuckDB decides whether two calls are the same expression without looking at their bind data: CScalarFunctionBindData::Equals (src/main/capi/scalar_function-c.cpp, DuckDB 1.5.5) compares only the function’s extra_info and callback pointer. Two calls with the same arguments are therefore merged by common-subexpression elimination and GROUP BY matching even if their bind callbacks stored different values, and one call’s bind data answers for both. Checked against 1.5.5: with a bind callback that stores a counter, SELECT f(i), f(i) runs the bind callback twice and returns the first call’s value in both columns.

This is harmless when the bind data depends only on what DuckDB does compare — the arguments (constant arguments included: f(i, 2) and f(i, 3) are different expressions and keep their own bind data), the argument types, and extra_info. It is wrong when the bind callback reads something else that can differ between two identical calls in one query: a counter, a clock, a random source. Mark such a function volatile: volatile calls are never merged (checked: the counter example then returns two different values).

Implementations§

Source§

impl<T: Send + Sync + 'static> ScalarBindData<T>

Source

pub fn set(info: &ScalarBindInfo, data: T)
where T: Clone,

Stores data as this function’s bind data, and registers the destructor and copy callback that go with it.

A second call through the same info replaces the first value, which is dropped then: DuckDB overwrites the stored pointer without running its destructor, so info remembers what this stored and frees it. The C API offers no way to read back what a bind callback stored, so a value stored through another ScalarBindInfo wrapper of the same bind call, or replaced by the raw set_bind_data, is leaked (never dropped).

Source

pub unsafe fn get<'a>(info: &ScalarFunctionInfo) -> Option<&'a T>

Borrows the bind data during execution.

Returns None if the bind callback never stored anything, or if DuckDB copied the bound expression and T::clone panicked while copying it. In the second case it also reports the panic message as this call’s error (ScalarFunctionInfo::set_error), so the query fails with it instead of answering as if no bind data had been set; a later set_error in the callback replaces that message (use try_get to handle it yourself).

§Safety
  • The bind callback must have stored a T via set — and nothing else. Reading a different type reinterprets memory.
  • The returned reference must not outlive the callback invocation that info belongs to. The lifetime 'a is the caller’s to choose and nothing ties it to info; DuckDB frees the bind data when the query finishes, and a reference kept past that reads freed memory.
Source

pub unsafe fn try_get<'a>( info: &ScalarFunctionInfo, ) -> Result<Option<&'a T>, String>

Borrows the bind data during execution, or returns the error a failed copy of it left: Ok(None) if the bind callback never stored anything, Err with the message get reports if DuckDB copied the bound expression and T::clone panicked.

§Errors

The panic message of the failed T::clone, with context.

§Safety

See get.

Source

pub unsafe fn get_from_init<'a>(info: &ScalarInitInfo) -> Option<&'a T>

Borrows the bind data during the init callback.

Like get, reports a failed copy as the init callback’s error (ScalarInitInfo::set_error) and returns None.

§Safety

See get.

Trait Implementations§

Source§

impl<T: Send + Sync + 'static> Debug for ScalarBindData<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 ScalarBindData<T>

§

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

§

impl<T> Send for ScalarBindData<T>

§

impl<T> Sync for ScalarBindData<T>

§

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

§

impl<T> UnsafeUnpin for ScalarBindData<T>

§

impl<T> UnwindSafe for ScalarBindData<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.