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(onset):DuckDBcopies 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.setregisters a generated copy callback that clonesT.
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>
impl<T: Send + Sync + 'static> ScalarBindData<T>
Sourcepub fn set(info: &ScalarBindInfo, data: T)where
T: Clone,
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).
Sourcepub unsafe fn get<'a>(info: &ScalarFunctionInfo) -> Option<&'a T>
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
Tviaset— and nothing else. Reading a different type reinterprets memory. - The returned reference must not outlive the callback invocation that
infobelongs to. The lifetime'ais the caller’s to choose and nothing ties it toinfo;DuckDBfrees the bind data when the query finishes, and a reference kept past that reads freed memory.
Sourcepub unsafe fn try_get<'a>(
info: &ScalarFunctionInfo,
) -> Result<Option<&'a T>, String>
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.
Sourcepub unsafe fn get_from_init<'a>(info: &ScalarInitInfo) -> Option<&'a T>
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.