Skip to main content

quack_rs/scalar/
typed_builder.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//! The builder the closure-based scalar constructors return, and the one
7//! `extern "C"` trampoline they all share.
8//!
9//! # Why a separate builder type
10//!
11//! A typed closure's trampoline reads each argument column as the Rust type the
12//! closure takes and writes the result as the Rust type it returns. Those reads
13//! and writes are only sound while the *declared* SQL signature matches. The
14//! plain [`ScalarFunctionBuilder`] lets safe code redeclare the signature at any
15//! time — `.returns(TypeId::Integer)` after an `i64` closure made `DuckDB`
16//! allocate a 4-byte-per-row result vector the trampoline then wrote 8 bytes
17//! per row into. [`TypedScalarFunctionBuilder`] therefore exposes only
18//! operations that cannot desynchronise the two.
19//!
20//! As a second line of defence, the trampoline checks every chunk's column
21//! count and physical types against the closure's signature before touching a
22//! single row, and reports a mismatch as a SQL error.
23
24use std::panic::AssertUnwindSafe;
25
26use libduckdb_sys::{
27    duckdb_connection, duckdb_data_chunk, duckdb_function_info, duckdb_get_type_id, duckdb_vector,
28};
29
30use crate::data_chunk::DataChunk;
31use crate::error::ExtensionError;
32use crate::scalar::builder::ScalarFunctionBuilder;
33use crate::types::{NullHandling, TypeId};
34use crate::vector::{vector_get_column_type, VectorWriter};
35
36/// The per-chunk executor a typed closure is compiled into.
37///
38/// Boxed once at build time and reached through one indirect call per chunk;
39/// the row loop inside is monomorphic.
40pub(super) type ChunkExec =
41    Box<dyn Fn(&DataChunk, &mut VectorWriter) -> Result<(), ExtensionError> + Send + Sync>;
42
43/// `extra_info` payload for a typed scalar function.
44struct TypedScalar {
45    params: Vec<TypeId>,
46    ret: TypeId,
47    exec: ChunkExec,
48}
49
50impl TypedScalar {
51    /// `extra_info` destructor.
52    ///
53    /// # Safety
54    ///
55    /// `ptr` must have come from `Box::into_raw` on a `Box<TypedScalar>`.
56    unsafe extern "C" fn destroy(ptr: *mut std::os::raw::c_void) {
57        if ptr.is_null() {
58            return;
59        }
60        // SAFETY: `ptr` came from `Box::into_raw` in `from_exec`. The boxed
61        // closure captures user data whose `Drop` may panic, and this is an
62        // `extern "C"` boundary with no error channel, so contain the unwind.
63        drop(crate::callback::catch_ffi_panic(|| unsafe {
64            drop(Box::from_raw(ptr.cast::<Self>()));
65        }));
66    }
67
68    /// Checks that the vectors `DuckDB` handed over have the types the closure
69    /// was compiled for.
70    ///
71    /// # Safety
72    ///
73    /// `output` must be the valid result vector for `chunk`'s invocation.
74    // A mismatch cannot be produced through this crate's public API any more;
75    // the end-to-end suite reaches it through a hand-written `Registrar`.
76    #[cfg_attr(test, mutants::skip)]
77    unsafe fn check_signature(
78        &self,
79        chunk: &DataChunk,
80        output: duckdb_vector,
81    ) -> Result<(), ExtensionError> {
82        if chunk.column_count() != self.params.len() {
83            return Err(ExtensionError::new(format!(
84                "quack-rs: typed scalar function was declared with {} argument(s) but was \
85                 called with {}; its signature must not be changed after construction",
86                self.params.len(),
87                chunk.column_count()
88            )));
89        }
90        for (i, expected) in self.params.iter().enumerate() {
91            // SAFETY: `i` is below the column count checked above.
92            let vector = unsafe { chunk.vector(i) };
93            // SAFETY: `vector` is a valid column of this chunk.
94            unsafe { check_vector(vector, *expected, &format!("argument {i}"))? };
95        }
96        // SAFETY: `output` is valid per this function's contract.
97        unsafe { check_vector(output, self.ret, "result") }
98    }
99}
100
101/// Fails unless `vector`'s type id is `expected`.
102///
103/// # Safety
104///
105/// `vector` must be a valid `duckdb_vector`.
106unsafe fn check_vector(
107    vector: duckdb_vector,
108    expected: TypeId,
109    what: &str,
110) -> Result<(), ExtensionError> {
111    // SAFETY: `vector` is valid per this function's contract.
112    let ty = unsafe { vector_get_column_type(vector) };
113    // SAFETY: `ty` is a live logical type owned for this scope.
114    let actual = unsafe { duckdb_get_type_id(ty.as_raw()) };
115    if actual == expected.to_duckdb_type() {
116        return Ok(());
117    }
118    Err(ExtensionError::new(format!(
119        "quack-rs: typed scalar function {what} is {actual_name} but the closure handles \
120         {expected_name}; its signature must not be changed after construction",
121        actual_name =
122            TypeId::try_from_duckdb_type(actual).map_or("an unknown type", TypeId::sql_name),
123        expected_name = expected.sql_name(),
124    )))
125}
126
127/// The single `extern "C"` callback every typed scalar function shares.
128///
129/// # Safety
130///
131/// Invoked by `DuckDB` with its own valid handles.
132unsafe extern "C" fn typed_trampoline(
133    info: duckdb_function_info,
134    input: duckdb_data_chunk,
135    output: duckdb_vector,
136) {
137    // SAFETY: `info` is the handle DuckDB passed in.
138    let fninfo = unsafe { crate::scalar::ScalarFunctionInfo::new(info) };
139
140    let outcome = crate::callback::catch_ffi_panic(AssertUnwindSafe(|| {
141        // SAFETY: `extra_info` was set by `from_exec` to a `Box<TypedScalar>`
142        // that DuckDB keeps alive until it calls `TypedScalar::destroy`.
143        // `TypedScalarFunctionBuilder` offers no way to replace it.
144        let raw = unsafe { fninfo.get_extra_info() };
145        if raw.is_null() {
146            return Err(ExtensionError::new(
147                "quack-rs: typed scalar function lost its extra_info",
148            ));
149        }
150        // SAFETY: same provenance as above; shared access only.
151        let typed = unsafe { &*raw.cast::<TypedScalar>() };
152        // SAFETY: `input` and `output` are valid for this call.
153        let chunk = unsafe { DataChunk::from_raw(input) };
154        // SAFETY: `output` is this invocation's result vector.
155        unsafe { typed.check_signature(&chunk, output)? };
156        // SAFETY: as above.
157        let mut writer = unsafe { VectorWriter::from_vector(output) };
158        (typed.exec)(&chunk, &mut writer)
159    }));
160
161    match outcome {
162        Ok(Ok(())) => {}
163        Ok(Err(e)) => fninfo.set_error(e.as_str()),
164        Err(message) => {
165            fninfo.set_error(&format!("quack-rs: scalar closure panicked: {message}"));
166        }
167    }
168}
169
170/// A scalar function built from a safe Rust closure, ready to register.
171///
172/// Returned by [`ScalarFunctionBuilder::map1`] and its siblings. The SQL
173/// signature is fixed by the closure's type, so this builder deliberately has
174/// no `returns`, `param`, `function`, `extra_info`, `bind` or `init`: each of
175/// those could make `DuckDB` hand the closure vectors of a different type than
176/// it reads and writes.
177///
178/// ```rust,compile_fail
179/// use quack_rs::scalar::ScalarFunctionBuilder;
180/// use quack_rs::types::TypeId;
181///
182/// # fn demo() -> Result<(), quack_rs::error::ExtensionError> {
183/// // An i64 result cannot be redeclared as a 4-byte INTEGER.
184/// let _ = ScalarFunctionBuilder::map1("widen", |x: i64| x + 1)?.returns(TypeId::Integer);
185/// # Ok(())
186/// # }
187/// ```
188///
189/// ```rust,compile_fail
190/// use quack_rs::scalar::ScalarFunctionBuilder;
191///
192/// quack_rs::scalar_callback!(other, |_info, _input, _output| {});
193///
194/// # fn demo() -> Result<(), quack_rs::error::ExtensionError> {
195/// // The trampoline cannot be swapped out from under the closure's state.
196/// let _ = ScalarFunctionBuilder::map1("f", |x: i64| x)?.function(other);
197/// # Ok(())
198/// # }
199/// ```
200#[must_use]
201pub struct TypedScalarFunctionBuilder {
202    inner: ScalarFunctionBuilder,
203}
204
205impl TypedScalarFunctionBuilder {
206    /// Builds a typed scalar function from a per-chunk executor.
207    ///
208    /// The public `map*` constructors on [`ScalarFunctionBuilder`] are thin
209    /// wrappers over this.
210    ///
211    /// Makes no `DuckDB` call, so a typed function can be built — and its
212    /// name inspected — without a live dispatch table. The type ids are not
213    /// checked here: every [`ScalarValue`][crate::scalar::ScalarValue] and
214    /// [`ScalarOut`][crate::scalar::ScalarOut] implementation in this crate
215    /// names a primitive type, and an out-of-crate implementation naming a
216    /// composite one is rejected by [`ScalarFunctionBuilder::register`] before
217    /// it allocates anything.
218    pub(super) fn from_exec(
219        name: &str,
220        params: &[TypeId],
221        ret: TypeId,
222        null_handling: NullHandling,
223        exec: ChunkExec,
224    ) -> Result<Self, ExtensionError> {
225        let builder = params
226            .iter()
227            .fold(ScalarFunctionBuilder::try_new(name)?, |b, id| b.param(*id))
228            .returns(ret)
229            .null_handling(null_handling);
230
231        let typed = TypedScalar {
232            params: params.to_vec(),
233            ret,
234            exec,
235        };
236        let raw = Box::into_raw(Box::new(typed)).cast::<std::os::raw::c_void>();
237        // SAFETY: `raw` is a live `Box<TypedScalar>` and `TypedScalar::destroy`
238        // is the matching destructor; DuckDB owns it from here.
239        let inner = unsafe {
240            builder
241                .function(typed_trampoline)
242                .extra_info(raw, Some(TypedScalar::destroy))
243        };
244        Ok(Self { inner })
245    }
246
247    /// Returns the function name.
248    pub fn name(&self) -> &str {
249        self.inner.name()
250    }
251
252    /// Marks this function as volatile: re-evaluated for every row even when
253    /// its arguments are constant (e.g. a random-number function).
254    ///
255    /// Only the function's stability changes; its signature does not.
256    pub fn volatile(mut self) -> Self {
257        self.inner = self.inner.volatile();
258        self
259    }
260
261    /// Registers the function on the given connection.
262    ///
263    /// # Errors
264    ///
265    /// Returns `ExtensionError` if a scalar function with this name and
266    /// parameter types already exists (which `DuckDB` would silently replace
267    /// or make ambiguous), or if `DuckDB` reports a registration failure — for
268    /// example, the name belongs to an aggregate function or a macro. See
269    /// [`ScalarFunctionBuilder::register`] for the collision rules.
270    ///
271    /// # Safety
272    ///
273    /// `con` must be a valid, open `duckdb_connection`.
274    pub unsafe fn register(self, con: duckdb_connection) -> Result<(), ExtensionError> {
275        // SAFETY: forwarded from this function's own contract.
276        unsafe { self.inner.register(con) }
277    }
278
279    /// Unwraps the underlying builder for a [`Registrar`][crate::connection::Registrar]
280    /// that only knows [`ScalarFunctionBuilder`].
281    ///
282    /// Crate-private so the signature cannot be edited through it; the
283    /// trampoline's per-chunk type check still guards a `Registrar`
284    /// implementation that edits it anyway.
285    pub(crate) fn into_inner(self) -> ScalarFunctionBuilder {
286        self.inner
287    }
288}
289
290impl core::fmt::Debug for TypedScalarFunctionBuilder {
291    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
292        f.debug_struct("TypedScalarFunctionBuilder")
293            .field("inner", &self.inner)
294            .finish()
295    }
296}
297
298#[cfg(test)]
299mod tests {
300    use super::*;
301
302    #[test]
303    fn destroy_tolerates_a_null_pointer() {
304        // SAFETY: the null case is explicitly handled.
305        unsafe { TypedScalar::destroy(std::ptr::null_mut()) };
306    }
307
308    #[test]
309    fn name_is_the_one_the_builder_was_created_with() {
310        let builder = ScalarFunctionBuilder::map1("double_it", |x: i64| x * 2)
311            .expect("builds without a live DuckDB");
312        assert_eq!(builder.name(), "double_it");
313        // A stability change keeps the name.
314        assert_eq!(builder.volatile().name(), "double_it");
315    }
316}