Skip to main content

Module init_data

Module init_data 

Source
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. Use FfiInitData to store global scan state (e.g., a file handle, row counter shared across threads).
  • Local init (local_init): Called once per scanning thread. Use FfiLocalInitData to 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::get hands several threads &T at once, which is why FfiInitData::set requires T: Send + Sync;
  • FfiInitData::get_mut would hand several threads &mut T at once — a data race. Keep mutable global state behind a Mutex or atomics and use get, or leave max_threads at 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§

FfiInitData
Type-safe global init data for DuckDB table functions.
FfiLocalInitData
Type-safe per-thread local init data for DuckDB table functions.