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}