Skip to main content

quack_rs/table/
init_data.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//! Type-safe init data management for table functions.
7//!
8//! `DuckDB` table functions have two init phases:
9//!
10//! - **Global init** (`init`): Called once per execution of a bound plan. Use
11//!   [`FfiInitData`] to store global scan state (e.g., a file handle, row
12//!   counter shared across threads).
13//! - **Local init** (`local_init`): Called once per scanning thread. Use
14//!   [`FfiLocalInitData`] to store per-thread scan state (e.g., a thread-local
15//!   buffer or offset).
16//!
17//! # Threads
18//!
19//! Global init data is shared by **every** concurrent scan call. `DuckDB` runs
20//! up to [`InitInfo::set_max_threads`][crate::table::InitInfo::set_max_threads]
21//! scans at once — whether or not `local_init` is set — and the default is 1.
22//! So with `max_threads > 1`:
23//!
24//! - [`FfiInitData::get`] hands several threads `&T` at once, which is why
25//!   [`FfiInitData::set`] requires `T: Send + Sync`;
26//! - [`FfiInitData::get_mut`] would hand several threads `&mut T` at once — a
27//!   data race. Keep mutable global state behind a `Mutex` or atomics and use
28//!   `get`, or leave `max_threads` at 1.
29//!
30//! Local init data belongs to one scanning task at a time, but that task may be
31//! resumed on a different worker thread, so [`FfiLocalInitData::set`] requires
32//! `T: Send`.
33//!
34//! # Example
35//!
36//! ```rust,no_run
37//! use quack_rs::table::{FfiInitData, FfiLocalInitData};
38//! use libduckdb_sys::{duckdb_init_info, duckdb_function_info};
39//!
40//! struct GlobalState { rows_remaining: u64 }
41//! struct LocalState  { thread_offset: u64 }
42//!
43//! unsafe extern "C" fn my_init(info: duckdb_init_info) {
44//!     unsafe { FfiInitData::<GlobalState>::set(info, GlobalState { rows_remaining: 1000 }); }
45//! }
46//!
47//! unsafe extern "C" fn my_local_init(info: duckdb_init_info) {
48//!     unsafe { FfiLocalInitData::<LocalState>::set(info, LocalState { thread_offset: 0 }); }
49//! }
50//!
51//! unsafe extern "C" fn my_scan(info: duckdb_function_info, _output: libduckdb_sys::duckdb_data_chunk) {
52//!     let _global = unsafe { FfiInitData::<GlobalState>::get(info) };
53//!     let _local  = unsafe { FfiLocalInitData::<LocalState>::get(info) };
54//! }
55//! ```
56
57use std::os::raw::c_void;
58
59use libduckdb_sys::{
60    duckdb_function_get_init_data, duckdb_function_get_local_init_data, duckdb_function_info,
61    duckdb_init_info, duckdb_init_set_init_data,
62};
63
64/// Type-safe global init data for `DuckDB` table functions.
65///
66/// Set in the global `init` callback; retrieved in `scan`.
67pub struct FfiInitData<T: 'static> {
68    _marker: std::marker::PhantomData<T>,
69}
70
71impl<T: 'static> FfiInitData<T> {
72    /// Stores `data` as the global init data for this query.
73    ///
74    /// Call inside your global `init` callback.
75    ///
76    /// `T` must be `Send + Sync`: the value is created on the init thread,
77    /// read by up to `max_threads` concurrent scan calls, and dropped on
78    /// whichever thread tears the plan down.
79    ///
80    /// # Safety
81    ///
82    /// - `info` must be a valid `duckdb_init_info` passed to the table function's
83    ///   global `init` callback, not its `local_init`. Both kinds of init data
84    ///   are stored through `duckdb_init_set_init_data`, so the callback alone
85    ///   decides which one this sets; called from `local_init`, it sets the
86    ///   local init data, which [`FfiLocalInitData::get`] would then read as its
87    ///   own type.
88    /// - Must be called at most once per init invocation.
89    pub unsafe fn set(info: duckdb_init_info, data: T)
90    where
91        T: Send + Sync,
92    {
93        let raw = Box::into_raw(Box::new(data)).cast::<c_void>();
94        // SAFETY: info is valid; raw is a heap allocation; destroy is a valid fn pointer.
95        unsafe {
96            duckdb_init_set_init_data(info, raw, Some(Self::destroy));
97        }
98    }
99
100    /// Retrieves a shared reference to the global init data from a scan callback.
101    ///
102    /// Returns `None` if no init data was set. Concurrent scan calls may hold
103    /// this reference at the same time; [`set`][Self::set] requires `T: Sync`
104    /// for that reason.
105    ///
106    /// # Safety
107    ///
108    /// - `info` must be a valid `duckdb_function_info` from a scan callback.
109    /// - `T` must be the type passed to [`set`][Self::set].
110    /// - No mutable reference to the same data must exist simultaneously.
111    /// - The returned reference must not outlive the scan callback: `DuckDB`
112    ///   destroys the data with the scan state.
113    pub unsafe fn get<'a>(info: duckdb_function_info) -> Option<&'a T> {
114        // SAFETY: info is valid per caller's contract.
115        let raw = unsafe { duckdb_function_get_init_data(info) };
116        if raw.is_null() {
117            return None;
118        }
119        // SAFETY: raw is non-null (checked above) and, by the `# Safety`
120        // clauses, is the live `Box<T>` that `set` leaked for this same `T`.
121        Some(unsafe { &*raw.cast::<T>() })
122    }
123
124    /// Retrieves a mutable reference to the global init data from a scan callback.
125    ///
126    /// Returns `None` if no init data was set.
127    ///
128    /// # Safety
129    ///
130    /// - `info` must be a valid `duckdb_function_info` from a scan callback.
131    /// - `T` must be the type passed to [`set`][Self::set].
132    /// - The returned reference must not outlive the scan callback: `DuckDB`
133    ///   destroys the data with the scan state.
134    /// - No other reference to the same data must exist simultaneously. Global
135    ///   init data is shared by every concurrent scan call of the query, so this
136    ///   holds only when the init callback left `max_threads` at 1 (the default)
137    ///   or the scan otherwise serialises calls to `get_mut`. With
138    ///   [`InitInfo::set_max_threads`][crate::table::InitInfo::set_max_threads]
139    ///   above 1, use [`get`][Self::get] and interior mutability (`Mutex`,
140    ///   atomics) instead — `local_init` does **not** change this.
141    pub unsafe fn get_mut<'a>(info: duckdb_function_info) -> Option<&'a mut T> {
142        // SAFETY: info is valid per caller's contract.
143        let raw = unsafe { duckdb_function_get_init_data(info) };
144        if raw.is_null() {
145            return None;
146        }
147        // SAFETY: raw is non-null (checked above) and, by the `# Safety`
148        // clauses, is the live `Box<T>` that `set` leaked for this same `T`;
149        // exclusivity is the caller's contract above.
150        Some(unsafe { &mut *raw.cast::<T>() })
151    }
152
153    /// Destroy callback: drops the `Box<T>`.
154    ///
155    /// # Pitfall L3: `T::drop` is user code
156    ///
157    /// `DuckDB` calls this through an `extern "C"` function pointer that has no
158    /// error channel, and an unwind across `extern "C"` aborts the process on
159    /// Rust 1.81+. The drop runs under
160    /// [`catch_ffi_panic`][crate::callback::catch_ffi_panic] so a panicking
161    /// `Drop` impl cannot take the session down.
162    ///
163    /// # Safety
164    ///
165    /// `ptr` must have been allocated by [`set`][FfiInitData::set].
166    pub unsafe extern "C" fn destroy(ptr: *mut c_void) {
167        if !ptr.is_null() {
168            // SAFETY: `ptr` came from `Box::into_raw` in `set`; `T::drop` is
169            // arbitrary user code, so its unwind is contained here.
170            drop(crate::callback::catch_ffi_panic(|| unsafe {
171                drop(Box::from_raw(ptr.cast::<T>()));
172            }));
173        }
174    }
175}
176
177/// Type-safe per-thread local init data for `DuckDB` table functions.
178///
179/// Set in the `local_init` callback; retrieved in `scan`.
180pub struct FfiLocalInitData<T: 'static> {
181    _marker: std::marker::PhantomData<T>,
182}
183
184impl<T: 'static> FfiLocalInitData<T> {
185    /// Stores `data` as the per-thread local init data.
186    ///
187    /// Call inside your `local_init` callback.
188    ///
189    /// `T` must be `Send`: a scanning task may be resumed on a different
190    /// worker thread, and the value is dropped wherever the plan is torn down.
191    ///
192    /// # Safety
193    ///
194    /// - `info` must be a valid `duckdb_init_info` passed to the table function's
195    ///   `local_init` callback, not its global `init`. Both kinds of init data
196    ///   are stored through `duckdb_init_set_init_data`, so the callback alone
197    ///   decides which one this sets; called from `init`, it sets the global
198    ///   init data, which [`FfiInitData::get`] would then read as its own type.
199    /// - Must be called at most once per `local_init` invocation.
200    pub unsafe fn set(info: duckdb_init_info, data: T)
201    where
202        T: Send,
203    {
204        let raw = Box::into_raw(Box::new(data)).cast::<c_void>();
205        // SAFETY: info is valid; raw is non-null. The same duckdb_init_set_init_data
206        // function is used for both global and local init; DuckDB tracks which
207        // phase is active when the callback is invoked.
208        unsafe {
209            duckdb_init_set_init_data(info, raw, Some(Self::destroy));
210        }
211    }
212
213    /// Retrieves a shared reference to the per-thread local init data.
214    ///
215    /// Returns `None` if no local init data was set.
216    ///
217    /// # Safety
218    ///
219    /// - `info` must be a valid `duckdb_function_info`.
220    /// - `T` must be the type passed to [`set`][Self::set].
221    /// - No mutable reference to the same data must exist simultaneously.
222    /// - The returned reference must not outlive the scan callback: `DuckDB`
223    ///   destroys the data with the scan state.
224    pub unsafe fn get<'a>(info: duckdb_function_info) -> Option<&'a T> {
225        // SAFETY: `info` is a valid `duckdb_function_info` per the first `# Safety` clause;
226        // `duckdb_function_get_local_init_data` only returns the stored
227        // `local_data.init_data` pointer (null if none, table_function-c.cpp).
228        let raw = unsafe { duckdb_function_get_local_init_data(info) };
229        if raw.is_null() {
230            return None;
231        }
232        // SAFETY: `raw` is non-null (checked above) and, by the second `# Safety`
233        // clause, the live `Box<T>` that `set` leaked for this same `T`; the
234        // third rules out a `&mut`, the fourth bounds `'a` by the scan call.
235        Some(unsafe { &*raw.cast::<T>() })
236    }
237
238    /// Retrieves a mutable reference to the per-thread local init data.
239    ///
240    /// Returns `None` if no local init data was set.
241    ///
242    /// # Safety
243    ///
244    /// - `info` must be a valid `duckdb_function_info`.
245    /// - `T` must be the type passed to [`set`][Self::set].
246    /// - No other reference to the same data must exist simultaneously.
247    /// - The returned reference must not outlive the scan callback: `DuckDB`
248    ///   destroys the data with the scan state.
249    pub unsafe fn get_mut<'a>(info: duckdb_function_info) -> Option<&'a mut T> {
250        // SAFETY: `info` is a valid `duckdb_function_info` per the first `# Safety` clause;
251        // `duckdb_function_get_local_init_data` only returns the stored
252        // `local_data.init_data` pointer (null if none, table_function-c.cpp).
253        let raw = unsafe { duckdb_function_get_local_init_data(info) };
254        if raw.is_null() {
255            return None;
256        }
257        // SAFETY: `raw` is non-null (checked above) and, by the second `# Safety`
258        // clause, the live `Box<T>` that `set` leaked for this same `T`; the
259        // third gives exclusivity, the fourth bounds `'a` by the scan call.
260        Some(unsafe { &mut *raw.cast::<T>() })
261    }
262
263    /// Destroy callback: drops the `Box<T>`.
264    ///
265    /// # Pitfall L3: `T::drop` is user code
266    ///
267    /// `DuckDB` calls this through an `extern "C"` function pointer that has no
268    /// error channel, and an unwind across `extern "C"` aborts the process on
269    /// Rust 1.81+. The drop runs under
270    /// [`catch_ffi_panic`][crate::callback::catch_ffi_panic] so a panicking
271    /// `Drop` impl cannot take the session down.
272    ///
273    /// # Safety
274    ///
275    /// `ptr` must have been allocated by [`set`][FfiLocalInitData::set].
276    pub unsafe extern "C" fn destroy(ptr: *mut c_void) {
277        if !ptr.is_null() {
278            // SAFETY: `ptr` came from `Box::into_raw` in `set`; `T::drop` is
279            // arbitrary user code, so its unwind is contained here.
280            drop(crate::callback::catch_ffi_panic(|| unsafe {
281                drop(Box::from_raw(ptr.cast::<T>()));
282            }));
283        }
284    }
285}
286
287impl<T: 'static> core::fmt::Debug for FfiInitData<T> {
288    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
289        f.write_str("FfiInitData<")?;
290        f.write_str(core::any::type_name::<T>())?;
291        f.write_str(">")
292    }
293}
294
295impl<T: 'static> core::fmt::Debug for FfiLocalInitData<T> {
296    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
297        f.write_str("FfiLocalInitData<")?;
298        f.write_str(core::any::type_name::<T>())?;
299        f.write_str(">")
300    }
301}
302
303#[cfg(test)]
304mod tests {
305    use super::*;
306
307    #[allow(dead_code)]
308    struct MyState {
309        counter: u64,
310    }
311
312    #[test]
313    fn destroy_null_is_noop() {
314        unsafe { FfiInitData::<MyState>::destroy(std::ptr::null_mut()) };
315        unsafe { FfiLocalInitData::<MyState>::destroy(std::ptr::null_mut()) };
316    }
317
318    #[test]
319    fn destroy_allocated_drops() {
320        let raw = Box::into_raw(Box::new(MyState { counter: 7 })).cast::<c_void>();
321        unsafe { FfiInitData::<MyState>::destroy(raw) };
322
323        let raw2 = Box::into_raw(Box::new(MyState { counter: 3 })).cast::<c_void>();
324        unsafe { FfiLocalInitData::<MyState>::destroy(raw2) };
325    }
326}