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(©_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}