Skip to main content

quack_rs/scalar/
state.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6//! Typed bind data and per-thread local state for scalar functions
7//! (`DuckDB` 1.5.0+).
8//!
9//! [`ScalarBindInfo::set_bind_data`][crate::scalar::ScalarBindInfo::set_bind_data]
10//! and
11//! [`ScalarInitInfo::set_state`][crate::scalar::ScalarInitInfo::set_state] take a
12//! raw pointer and a `duckdb_delete_callback_t`, which means every extension
13//! that wants bind data writes its own:
14//!
15//! ```rust,ignore
16//! unsafe extern "C" fn drop_bind(ptr: *mut c_void) {
17//!     if !ptr.is_null() {
18//!         drop(unsafe { Box::from_raw(ptr.cast::<BindData>()) });  // aborts if
19//!     }                                                           // Drop panics
20//! }
21//! ```
22//!
23//! That is the hazard [`FfiState`][crate::aggregate::FfiState] and
24//! [`FfiBindData`][crate::table::FfiBindData] exist to remove for aggregates and
25//! table functions: an unwind out of an `extern "C" fn` is a process abort on
26//! Rust 1.81+, and `BindData`'s `Drop` is arbitrary user code. [`ScalarBindData`]
27//! and [`ScalarLocalState`] are the same thing for scalar functions — the
28//! destructor is generated, panic-safe, and impossible to forget.
29//!
30//! # Lifecycle
31//!
32//! ```text
33//! bind        → ScalarBindData::<T>::set(&bind_info, value)
34//! init        → ScalarBindData::<T>::get_from_init(&init_info)   (read)
35//!               ScalarLocalState::<S>::set(&init_info, state)    (per thread)
36//! execute     → ScalarBindData::<T>::get(&function_info)         (read)
37//!               ScalarLocalState::<S>::get_mut(&function_info)   (read/write)
38//! ```
39//!
40//! # Example
41//!
42//! ```rust,no_run
43//! use quack_rs::scalar::state::ScalarBindData;
44//! use quack_rs::scalar::{ScalarBindInfo, ScalarFunctionInfo};
45//!
46//! #[derive(Clone)]
47//! struct Factor(i64);
48//!
49//! # #[allow(unused)]
50//! unsafe extern "C" fn my_bind(info: quack_rs::scalar::RawScalarBindInfo) {
51//!     // SAFETY: DuckDB passes a valid bind info.
52//!     let bind = unsafe { ScalarBindInfo::new(info) };
53//!     ScalarBindData::set(&bind, Factor(10));
54//! }
55//!
56//! quack_rs::scalar_callback!(my_func, |info, input, output| {
57//!     // SAFETY: DuckDB passes a valid function info.
58//!     let fninfo = unsafe { ScalarFunctionInfo::new(info) };
59//!     // SAFETY: `my_bind` stored a `Factor`, and nothing else did.
60//!     let factor = unsafe { ScalarBindData::<Factor>::get(&fninfo) };
61//!     let _ = factor.map(|f| f.0);
62//! });
63//! ```
64//!
65//! # Thread safety
66//!
67//! `DuckDB` hands the *same* bind data to every thread executing the query
68//! (`CAPIScalarFunction` in `src/main/capi/scalar_function-c.cpp` reads it
69//! through the shared bound expression), so bind data must be `Send + Sync`.
70//! Local state is per thread but may be freed on a different thread from the
71//! one that created it, so it must be `Send`. Both bounds are enforced:
72//!
73//! ```rust,compile_fail
74//! # use quack_rs::scalar::{ScalarBindData, ScalarBindInfo};
75//! fn bind(info: &ScalarBindInfo) {
76//!     // `Rc` is neither `Send` nor `Sync`: rejected.
77//!     ScalarBindData::set(info, std::rc::Rc::new(1_i64));
78//! }
79//! ```
80//!
81//! ```rust,compile_fail
82//! # use quack_rs::scalar::{ScalarInitInfo, ScalarLocalState};
83//! fn init(info: &ScalarInitInfo) {
84//!     // `Rc` is not `Send`: rejected.
85//!     ScalarLocalState::set(info, std::rc::Rc::new(1_i64));
86//! }
87//! ```
88
89use std::marker::PhantomData;
90use std::os::raw::c_void;
91
92use crate::scalar::info::{ScalarBindInfo, ScalarFunctionInfo, ScalarInitInfo};
93
94/// Frees a `Box<T>` behind a `duckdb_delete_callback_t`, containing any panic.
95///
96/// # Safety
97///
98/// `ptr` must have come from `Box::into_raw` on a `Box<T>`, and must not be
99/// freed by anyone else.
100unsafe extern "C" fn drop_boxed<T>(ptr: *mut c_void) {
101    if ptr.is_null() {
102        return;
103    }
104    // SAFETY: `ptr` came from `Box::into_raw(Box::<T>::new(..))`. `T::drop` is
105    // arbitrary user code and this is an `extern "C"` boundary with no error
106    // channel, so the unwind is contained here rather than aborting.
107    drop(crate::callback::catch_ffi_panic(|| unsafe {
108        drop(Box::from_raw(ptr.cast::<T>()));
109    }));
110}
111
112/// What a [`ScalarBindData`] allocation holds.
113enum Slot<T> {
114    /// The value the bind callback stored, or a clone of it.
115    Value(T),
116    /// `T::clone` panicked while `DuckDB` copied the bound expression: the
117    /// panic message, reported when the copy's bind data is read.
118    CopyFailed(String),
119}
120
121/// Clones a `Box<Slot<T>>` behind a `duckdb_copy_callback_t`, containing any
122/// panic.
123///
124/// If `T::clone` panics, the copy holds the panic message instead of a value
125/// ([`Slot::CopyFailed`]), which [`ScalarBindData::get`] reports as the
126/// call's error. `DuckDB`'s copy callback has no error channel, and a null
127/// copy is read as "no bind data", a silent wrong answer.
128///
129/// # Safety
130///
131/// `ptr` must be null or point to a live `Slot<T>` produced by
132/// [`ScalarBindData::set`] or by this function.
133unsafe extern "C" fn clone_slot<T: Clone>(ptr: *mut c_void) -> *mut c_void {
134    if ptr.is_null() {
135        return std::ptr::null_mut();
136    }
137    // `T::clone` is arbitrary user code and this is an `extern "C"` boundary
138    // with no error channel, so the unwind is contained here.
139    let copy = crate::callback::catch_ffi_panic(|| {
140        // SAFETY: `ptr` points to a live `Slot<T>` owned by the bind data
141        // being copied; shared access only.
142        match unsafe { &*ptr.cast::<Slot<T>>() } {
143            Slot::Value(value) => Slot::Value(value.clone()),
144            Slot::CopyFailed(message) => Slot::CopyFailed(message.clone()),
145        }
146    })
147    .unwrap_or_else(Slot::CopyFailed);
148    Box::into_raw(Box::new(copy)).cast::<c_void>()
149}
150
151/// The bind data behind `raw`: the value, or `None` after reporting a failed
152/// copy through `report`.
153///
154/// # Safety
155///
156/// `raw` must be null or a live `Slot<T>` that outlives `'a`.
157unsafe fn read_slot<'a, T>(raw: *mut c_void, report: impl FnOnce(&str)) -> Option<&'a T> {
158    // SAFETY: forwarded from this function's own contract.
159    match unsafe { raw.cast::<Slot<T>>().as_ref() }? {
160        Slot::Value(value) => Some(value),
161        Slot::CopyFailed(message) => {
162            report(&copy_failure(message));
163            None
164        }
165    }
166}
167
168/// The error a failed bind-data copy is reported as.
169fn copy_failure(message: &str) -> String {
170    format!(
171        "quack-rs: DuckDB copied this function call (the optimizer does, e.g. to push a filter \
172         down) and the bind data's Clone panicked, so the copy has no bind data: {message}"
173    )
174}
175
176/// Type-safe bind data for a `DuckDB` scalar function.
177///
178/// Set once in the bind callback; read in init and in every execution. `DuckDB`
179/// owns the allocation and frees it through a generated, panic-safe destructor
180/// when the bound function is discarded.
181///
182/// # Why `T: Clone + Send + Sync`
183///
184/// - **`Send + Sync`**: every thread executing the query reads the same value
185///   concurrently (see the [module docs][self]).
186/// - **`Clone`** (on [`set`][Self::set]): `DuckDB` copies the bound expression
187///   whenever the optimizer duplicates it — filter pushdown through a
188///   projection does — and a copy made without a copy callback has **no** bind
189///   data at all. `set` registers a generated copy callback that clones `T`.
190///
191/// For data that is expensive or impossible to clone, store an
192/// [`Arc<T>`][std::sync::Arc]: cloning it is a reference-count bump, and every
193/// copy then shares one value.
194///
195/// # Bind data must be a function of the call's arguments
196///
197/// `DuckDB` decides whether two calls are the same expression without looking
198/// at their bind data: `CScalarFunctionBindData::Equals`
199/// (`src/main/capi/scalar_function-c.cpp`, `DuckDB` 1.5.5) compares only the
200/// function's `extra_info` and callback pointer. Two calls with the same
201/// arguments are therefore merged by common-subexpression elimination and
202/// `GROUP BY` matching even if their bind callbacks stored different values,
203/// and one call's bind data answers for both. Checked against 1.5.5: with a
204/// bind callback that stores a counter, `SELECT f(i), f(i)` runs the bind
205/// callback twice and returns the first call's value in both columns.
206///
207/// This is harmless when the bind data depends only on what `DuckDB` does
208/// compare — the arguments (constant arguments included: `f(i, 2)` and
209/// `f(i, 3)` are different expressions and keep their own bind data), the
210/// argument types, and `extra_info`. It is wrong when the bind callback reads
211/// something else that can differ between two identical calls in one query:
212/// a counter, a clock, a random source. Mark such a function
213/// [`volatile`][crate::scalar::ScalarFunctionBuilder::volatile]: volatile
214/// calls are never merged (checked: the counter example then returns two
215/// different values).
216pub struct ScalarBindData<T: Send + Sync + 'static> {
217    _marker: PhantomData<T>,
218}
219
220impl<T: Send + Sync + 'static> ScalarBindData<T> {
221    /// Stores `data` as this function's bind data, and registers the
222    /// destructor and copy callback that go with it.
223    ///
224    /// A second call through the same `info` replaces the first value, which
225    /// is dropped then: `DuckDB` overwrites the stored pointer without running
226    /// its destructor, so `info` remembers what this stored and frees it. The
227    /// C API offers no way to read back what a bind callback stored, so a
228    /// value stored through another [`ScalarBindInfo`] wrapper of the same
229    /// bind call, or replaced by the raw
230    /// [`set_bind_data`][ScalarBindInfo::set_bind_data], is leaked (never
231    /// dropped).
232    // The body is FFI calls; with no live engine there is no way to observe
233    // whether they happened, so the `--lib` mutation run cannot kill `with
234    // ()`. Covered end to end by the typed scalar-bind tests.
235    #[cfg_attr(test, mutants::skip)]
236    pub fn set(info: &ScalarBindInfo, data: T)
237    where
238        T: Clone,
239    {
240        let raw = Box::into_raw(Box::new(Slot::Value(data))).cast::<c_void>();
241        let replaced = info.take_typed_bind_data();
242        // SAFETY: `raw` is a fresh `Box<Slot<T>>`; `drop_boxed::<Slot<T>>` is
243        // the matching destructor and `clone_slot::<T>` produces allocations
244        // the same destructor frees. DuckDB owns it from here.
245        unsafe {
246            info.set_bind_data(raw, Some(drop_boxed::<Slot<T>>));
247            info.set_bind_data_copy(Some(clone_slot::<T>));
248        }
249        info.replace_typed_bind_data((raw, drop_boxed::<Slot<T>>));
250        if let Some((previous, destroy)) = replaced {
251            // SAFETY: `previous` is the value an earlier `set` through `info`
252            // stored with `destroy` as its destructor; the call above
253            // overwrote DuckDB's only pointer to it (a plain assignment in
254            // `duckdb_scalar_function_set_bind_data`), and no copy of it can
255            // exist yet: copies are made after the bind callback returns.
256            unsafe { destroy(previous) };
257        }
258    }
259
260    /// Borrows the bind data during execution.
261    ///
262    /// Returns `None` if the bind callback never stored anything, or if
263    /// `DuckDB` copied the bound expression and `T::clone` panicked while
264    /// copying it. In the second case it also reports the panic message as
265    /// this call's error ([`ScalarFunctionInfo::set_error`]), so the query
266    /// fails with it instead of answering as if no bind data had been set; a
267    /// later `set_error` in the callback replaces that message (use
268    /// [`try_get`][Self::try_get] to handle it yourself).
269    ///
270    /// # Safety
271    ///
272    /// - The bind callback must have stored a `T` via [`set`][Self::set] — and
273    ///   nothing else. Reading a different type reinterprets memory.
274    /// - The returned reference must not outlive the callback invocation that
275    ///   `info` belongs to. The lifetime `'a` is the caller's to choose and
276    ///   nothing ties it to `info`; `DuckDB` frees the bind data when the query
277    ///   finishes, and a reference kept past that reads freed memory.
278    #[must_use]
279    pub unsafe fn get<'a>(info: &ScalarFunctionInfo) -> Option<&'a T> {
280        // SAFETY: forwarded from this function's own contract.
281        let raw = unsafe { info.get_bind_data() };
282        // SAFETY: `raw` is null or was produced by `set` (or copied from it),
283        // and DuckDB keeps it alive for the whole execution.
284        unsafe { read_slot(raw, |message| info.set_error(message)) }
285    }
286
287    /// Borrows the bind data during execution, or returns the error a failed
288    /// copy of it left: `Ok(None)` if the bind callback never stored
289    /// anything, `Err` with the message [`get`][Self::get] reports if
290    /// `DuckDB` copied the bound expression and `T::clone` panicked.
291    ///
292    /// # Errors
293    ///
294    /// The panic message of the failed `T::clone`, with context.
295    ///
296    /// # Safety
297    ///
298    /// See [`get`][Self::get].
299    pub unsafe fn try_get<'a>(info: &ScalarFunctionInfo) -> Result<Option<&'a T>, String> {
300        // SAFETY: forwarded from this function's own contract.
301        let raw = unsafe { info.get_bind_data() };
302        let mut failure = None;
303        // SAFETY: as in `get`.
304        let value = unsafe { read_slot(raw, |message| failure = Some(message.to_owned())) };
305        failure.map_or(Ok(value), Err)
306    }
307
308    /// Borrows the bind data during the init callback.
309    ///
310    /// Like [`get`][Self::get], reports a failed copy as the init callback's
311    /// error ([`ScalarInitInfo::set_error`]) and returns `None`.
312    ///
313    /// # Safety
314    ///
315    /// See [`get`][Self::get].
316    #[must_use]
317    pub unsafe fn get_from_init<'a>(info: &ScalarInitInfo) -> Option<&'a T> {
318        // SAFETY: forwarded from this function's own contract.
319        let raw = unsafe { info.get_bind_data() };
320        // SAFETY: as in `get`.
321        unsafe { read_slot(raw, |message| info.set_error(message)) }
322    }
323}
324
325impl<T: Send + Sync + 'static> core::fmt::Debug for ScalarBindData<T> {
326    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
327        f.write_str("ScalarBindData<")?;
328        f.write_str(core::any::type_name::<T>())?;
329        f.write_str(">")
330    }
331}
332
333/// Type-safe per-thread local state for a `DuckDB` scalar function.
334///
335/// `DuckDB` calls the init callback once per execution thread, so each thread
336/// gets its own `T` and [`get_mut`][Self::get_mut] hands out `&mut T` without
337/// synchronisation. That is why `T` need only be `Send`, not `Sync` — and why a
338/// counter kept here is per-thread, not global. It must be `Send` because the
339/// thread that frees it need not be the one that created it.
340pub struct ScalarLocalState<T: Send + 'static> {
341    _marker: PhantomData<T>,
342}
343
344impl<T: Send + 'static> ScalarLocalState<T> {
345    /// Stores `state` as this thread's local state.
346    ///
347    /// Call at most once per init invocation: `DuckDB` overwrites the stored
348    /// pointer on a second call **without** freeing the first value, so the
349    /// first value is leaked (never dropped). The C API offers no way to read
350    /// the state back from an init callback, so quack-rs cannot free it.
351    // As `ScalarBindData::set`: one FFI call, no observable effect without a
352    // live engine.
353    #[cfg_attr(test, mutants::skip)]
354    pub fn set(info: &ScalarInitInfo, state: T) {
355        let raw = Box::into_raw(Box::new(state)).cast::<c_void>();
356        // SAFETY: `raw` is a fresh `Box<T>` and `drop_boxed::<T>` is the
357        // matching destructor; DuckDB owns it from here.
358        unsafe { info.set_state(raw, Some(drop_boxed::<T>)) };
359    }
360
361    /// Mutably borrows this thread's local state during execution.
362    ///
363    /// Returns `None` if the init callback never stored anything.
364    ///
365    /// # Safety
366    ///
367    /// - The init callback must have stored a `T` via [`set`][Self::set].
368    /// - Only one borrow may be live at a time within a callback invocation.
369    /// - The returned reference must not outlive the callback invocation that
370    ///   `info` belongs to. The lifetime `'a` is the caller's to choose and
371    ///   nothing ties it to `info`; `DuckDB` frees the local state when the
372    ///   thread's execution ends.
373    #[must_use]
374    pub unsafe fn get_mut<'a>(info: &ScalarFunctionInfo) -> Option<&'a mut T> {
375        // SAFETY: forwarded from this function's own contract.
376        let raw = unsafe { info.get_state() };
377        if raw.is_null() {
378            return None;
379        }
380        // SAFETY: `raw` was produced by `set` on this thread, and DuckDB keeps
381        // it alive for the whole execution. The caller promises exclusivity.
382        Some(unsafe { &mut *raw.cast::<T>() })
383    }
384}
385
386impl<T: Send + 'static> core::fmt::Debug for ScalarLocalState<T> {
387    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
388        f.write_str("ScalarLocalState<")?;
389        f.write_str(core::any::type_name::<T>())?;
390        f.write_str(">")
391    }
392}
393
394#[cfg(test)]
395mod tests {
396    use super::*;
397    use std::sync::atomic::{AtomicUsize, Ordering};
398
399    static DROPS: AtomicUsize = AtomicUsize::new(0);
400
401    struct Tracked;
402    impl Drop for Tracked {
403        fn drop(&mut self) {
404            DROPS.fetch_add(1, Ordering::SeqCst);
405        }
406    }
407
408    #[test]
409    fn the_generated_destructor_frees_exactly_once() {
410        DROPS.store(0, Ordering::SeqCst);
411        let raw = Box::into_raw(Box::new(Tracked)).cast::<c_void>();
412        // SAFETY: `raw` came from `Box::into_raw(Box::new(Tracked))`.
413        unsafe { drop_boxed::<Tracked>(raw) };
414        assert_eq!(DROPS.load(Ordering::SeqCst), 1);
415    }
416
417    #[test]
418    fn the_generated_destructor_tolerates_null() {
419        // SAFETY: the null case is handled explicitly.
420        unsafe { drop_boxed::<Tracked>(std::ptr::null_mut()) };
421    }
422
423    struct DropBomb;
424    impl Drop for DropBomb {
425        fn drop(&mut self) {
426            panic!("bind data destructor deliberately exploded");
427        }
428    }
429
430    #[test]
431    fn a_panicking_drop_does_not_escape_the_destructor() {
432        let raw = Box::into_raw(Box::new(DropBomb)).cast::<c_void>();
433        // Reaching the line after this is the assertion: without the
434        // `catch_ffi_panic` inside `drop_boxed`, the unwind would hit the
435        // `extern "C"` boundary and abort the test binary.
436        // SAFETY: `raw` came from `Box::into_raw(Box::new(DropBomb))`.
437        unsafe { drop_boxed::<DropBomb>(raw) };
438    }
439
440    #[derive(Debug, PartialEq)]
441    struct Cloned(Vec<u8>);
442    impl Clone for Cloned {
443        fn clone(&self) -> Self {
444            assert!(self.0 != b"bomb", "bind data clone deliberately exploded");
445            Self(self.0.clone())
446        }
447    }
448
449    fn slot(value: Cloned) -> *mut c_void {
450        Box::into_raw(Box::new(Slot::Value(value))).cast()
451    }
452
453    /// The value behind a slot, or the failure it reports.
454    fn read(raw: *mut c_void) -> Result<Option<Cloned>, String> {
455        let mut failure = None;
456        // SAFETY: every `raw` here is null or a live `Slot<Cloned>`.
457        let value = unsafe { read_slot::<Cloned>(raw, |m| failure = Some(m.to_owned())) };
458        failure.map_or_else(|| Ok(value.cloned()), Err)
459    }
460
461    #[test]
462    fn the_generated_copy_callback_produces_an_independent_box() {
463        let raw = slot(Cloned(vec![1, 2, 3]));
464        // SAFETY: `raw` is a live `Box<Slot<Cloned>>`.
465        let copy = unsafe { clone_slot::<Cloned>(raw) };
466        assert!(!copy.is_null());
467        assert_ne!(copy, raw, "a copy must be a separate allocation");
468        assert_eq!(read(copy), Ok(Some(Cloned(vec![1, 2, 3]))));
469        // SAFETY: both are live `Box<Slot<Cloned>>` allocations.
470        unsafe { drop_boxed::<Slot<Cloned>>(raw) };
471        // The copy survives the original being freed.
472        assert_eq!(read(copy), Ok(Some(Cloned(vec![1, 2, 3]))));
473        // SAFETY: as above.
474        unsafe { drop_boxed::<Slot<Cloned>>(copy) };
475    }
476
477    #[test]
478    fn the_generated_copy_callback_tolerates_null() {
479        // SAFETY: the null case is handled explicitly.
480        assert!(unsafe { clone_slot::<Cloned>(std::ptr::null_mut()) }.is_null());
481        assert_eq!(read(std::ptr::null_mut()), Ok(None), "no bind data");
482    }
483
484    /// FFI-6: a panicking `Clone` used to make the copy null, which reads as
485    /// "no bind data" (the query answered wrongly, the panic message was
486    /// lost). The copy now carries the message, reading it reports it, and a
487    /// copy of the copy keeps it.
488    #[test]
489    fn a_panicking_clone_is_reported_when_the_copy_is_read() {
490        let raw = slot(Cloned(b"bomb".to_vec()));
491        // SAFETY: `raw` is a live `Box<Slot<Cloned>>`.
492        let copy = unsafe { clone_slot::<Cloned>(raw) };
493        assert!(!copy.is_null(), "a failed clone is not 'no bind data'");
494        let err = read(copy).expect_err("the failure is reported");
495        assert!(
496            err.contains("bind data clone deliberately exploded") && err.contains("Clone panicked"),
497            "{err}"
498        );
499        // SAFETY: `copy` is a live `Box<Slot<Cloned>>`.
500        let again = unsafe { clone_slot::<Cloned>(copy) };
501        assert_eq!(read(again), Err(err));
502        // SAFETY: each is live and freed once.
503        unsafe {
504            drop_boxed::<Slot<Cloned>>(raw);
505            drop_boxed::<Slot<Cloned>>(copy);
506            drop_boxed::<Slot<Cloned>>(again);
507        }
508    }
509
510    #[test]
511    fn debug_names_the_payload_type() {
512        let s = format!(
513            "{:?}",
514            ScalarBindData::<u32> {
515                _marker: PhantomData
516            }
517        );
518        assert!(s.contains("u32"), "{s}");
519        let s = format!(
520            "{:?}",
521            ScalarLocalState::<u64> {
522                _marker: PhantomData
523            }
524        );
525        assert!(s.contains("u64"), "{s}");
526    }
527}