Expand description
Type-safe init data management for table functions.
DuckDB table functions have two init phases:
- Global init (
init): Called once per execution of a bound plan. UseFfiInitDatato store global scan state (e.g., a file handle, row counter shared across threads). - Local init (
local_init): Called once per scanning thread. UseFfiLocalInitDatato store per-thread scan state (e.g., a thread-local buffer or offset).
§Threads
Global init data is shared by every concurrent scan call. DuckDB runs
up to InitInfo::set_max_threads
scans at once — whether or not local_init is set — and the default is 1.
So with max_threads > 1:
FfiInitData::gethands several threads&Tat once, which is whyFfiInitData::setrequiresT: Send + Sync;FfiInitData::get_mutwould hand several threads&mut Tat once — a data race. Keep mutable global state behind aMutexor atomics and useget, or leavemax_threadsat 1.
Local init data belongs to one scanning task at a time, but that task may be
resumed on a different worker thread, so FfiLocalInitData::set requires
T: Send.
§Example
use quack_rs::table::{FfiInitData, FfiLocalInitData};
use libduckdb_sys::{duckdb_init_info, duckdb_function_info};
struct GlobalState { rows_remaining: u64 }
struct LocalState { thread_offset: u64 }
unsafe extern "C" fn my_init(info: duckdb_init_info) {
unsafe { FfiInitData::<GlobalState>::set(info, GlobalState { rows_remaining: 1000 }); }
}
unsafe extern "C" fn my_local_init(info: duckdb_init_info) {
unsafe { FfiLocalInitData::<LocalState>::set(info, LocalState { thread_offset: 0 }); }
}
unsafe extern "C" fn my_scan(info: duckdb_function_info, _output: libduckdb_sys::duckdb_data_chunk) {
let _global = unsafe { FfiInitData::<GlobalState>::get(info) };
let _local = unsafe { FfiLocalInitData::<LocalState>::get(info) };
}Structs§
- FfiInit
Data - Type-safe global init data for
DuckDBtable functions. - FfiLocal
Init Data - Type-safe per-thread local init data for
DuckDBtable functions.