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}