Skip to main content

Module callback

Module callback 

Source
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

MacroWrapsReports through
scalar_callback!scalar function executionduckdb_scalar_function_set_error
table_bind_callback!table function bindduckdb_bind_set_error
table_init_callback!table function init / local initduckdb_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 scanduckdb_function_set_error, then chunk size 0
aggregate_update_callback!aggregate updateduckdb_aggregate_function_set_error
aggregate_combine_callback!aggregate combineduckdb_aggregate_function_set_error
aggregate_finalize_callback!aggregate finalizeduckdb_aggregate_function_set_error
aggregate_destroy_callback!aggregate state destructor(no error channel — panic is swallowed)
cast_callback!cast functionduckdb_cast_function_set_error, returns false
replacement_scan_callback!replacement scanduckdb_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 regular CAST when its body returns false without 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_payload unwinds through before it leaks what is left rather than keep going.

Functions§

catch_ffi_panic
Runs body with unwinding contained, returning the panic message on unwind.
drop_panic_payload
Drops a caught panic payload, containing any panic its Drop raises.
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_unwind payload.
take_panic_message
Extracts the panic message from a caught payload, then disposes of the payload with drop_panic_payload.