Expand description
Panic-safe callback wrapper macros for DuckDB extension callbacks.
Every DuckDB callback is an unsafe extern "C" fn, and a Rust panic that
reaches that boundary aborts the process — taking the user’s DuckDB session,
and any application embedding it, with it. These macros wrap the body in
std::panic::catch_unwind and route the panic message to whichever
set_error DuckDB provides for that callback kind, so a bug in extension
code becomes an ordinary SQL error.
§Macros
| Macro | Wraps | Reports through |
|---|---|---|
scalar_callback! | scalar function execution | duckdb_scalar_function_set_error |
table_bind_callback! | table function bind | duckdb_bind_set_error |
table_init_callback! | table function init / local init | duckdb_init_set_error |
scalar_bind_callback! | scalar function bind (duckdb-1-5) | duckdb_scalar_function_bind_set_error |
scalar_init_callback! | scalar function init (duckdb-1-5) | duckdb_scalar_function_init_set_error |
table_scan_callback! | table function scan | duckdb_function_set_error, then chunk size 0 |
aggregate_update_callback! | aggregate update | duckdb_aggregate_function_set_error |
aggregate_combine_callback! | aggregate combine | duckdb_aggregate_function_set_error |
aggregate_finalize_callback! | aggregate finalize | duckdb_aggregate_function_set_error |
aggregate_destroy_callback! | aggregate state destructor | (no error channel — panic is swallowed) |
cast_callback! | cast function | duckdb_cast_function_set_error, returns false |
replacement_scan_callback! | replacement scan | duckdb_replacement_scan_set_error |
§panic = "abort"
catch_unwind cannot catch anything when the crate is built with
panic = "abort", which silently disables everything in this module. Keep
extension crates on panic = "unwind" — the quack-rs scaffold generates that,
and entry_point! and
entry_point_v2! refuse to compile without it.
§What no guard can catch
Some failures abort the process, and with it the DuckDB host, whatever
quack-rs does: a panic raised while another panic is already unwinding (a
Drop that panics during the unwind: Rust prints “panic in a destructor
during cleanup” and aborts), a panic hook that itself panics, and running
out of memory (Rust’s default allocation-error handler aborts, also when
the allocation is the one that formats a panic’s message). A caught panic is
still reported by the panic hook, which by default prints it to stderr.
§The body returns ()
A body runs under catch_unwind, and its value is discarded. So
every body except cast_callback!’s (which returns the cast’s bool) must
have type (): a body that used ? would otherwise compile, and the error
it returned would be dropped without being reported.
quack_rs::scalar_callback!(parse_or_drop, |info, input, output| {
let _n: i64 = "not a number".parse()?; // dropped, not reported
Ok::<(), std::num::ParseIntError>(())
});Report such an error with the callback’s set_error instead.
§The body is not an unsafe context
The generated function is an unsafe extern "C" fn, but the body is
expanded as an ordinary nested fn, so an unsafe operation in it needs its
own unsafe block, as anywhere else in safe code. Until the fifth audit the
body was a closure inside the unsafe fn and inherited its unsafe context:
on edition 2021 this compiled with no unsafe keyword and no warning.
quack_rs::scalar_callback!(reads_a_raw_pointer, |info, input, output| {
let _ = (info, output);
let _first_byte = *input.cast::<u8>();
});quack_rs::cast_callback!(casts_by_hand, |info, count, input, output| {
let _ = (info, count, output);
*input.cast::<u8>() == 0
});§Example: Scalar callback
use quack_rs::data_chunk::DataChunk;
use quack_rs::vector::VectorWriter;
quack_rs::scalar_callback!(my_func, |info, input, output| {
let chunk = unsafe { DataChunk::from_raw(input) };
let reader = unsafe { chunk.reader(0) }; // once per chunk, not per row
let mut writer = unsafe { VectorWriter::from_vector(output) };
for row in 0..chunk.size() {
let val = unsafe { reader.read_i64(row) };
unsafe { writer.write_i64(row, val * 2) };
}
});§Example: Table scan callback
use quack_rs::data_chunk::DataChunk;
quack_rs::table_scan_callback!(my_scan, |info, output| {
let chunk = unsafe { DataChunk::from_raw(output) };
let mut writer = unsafe { chunk.writer(0) };
unsafe { writer.write_i64(0, 42) };
unsafe { chunk.set_size(1) };
});Constants§
- CAST_
FAILED_ WITHOUT_ MESSAGE - The error a
cast_callback!function reports in a regularCASTwhen its body returnsfalsewithout setting a message. - EMPTY_
PANIC_ PLACEHOLDER - What the callback macros report for a panic whose message is empty
(
panic!("")). - MAX_
NESTED_ PAYLOAD_ DROPS - How many nested panicking payload drops
drop_panic_payloadunwinds through before it leaks what is left rather than keep going.
Functions§
- catch_
ffi_ panic - Runs
bodywith unwinding contained, returning the panic message on unwind. - drop_
panic_ payload - Drops a caught panic payload, containing any panic its
Dropraises. - message_
to_ c_ string - Converts a panic message into a
CString, replacing any interior NUL. - panic_
c_ message - Turns a caught panic into the C string a callback macro reports.
- panic_
message - Extracts a human-readable message from a
catch_unwindpayload. - take_
panic_ message - Extracts the panic message from a caught payload, then disposes of the
payload with
drop_panic_payload.