quack_rs/aggregate/info.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//! Ergonomic wrapper around `duckdb_function_info` for aggregate function callbacks.
7
8use std::os::raw::c_void;
9
10use libduckdb_sys::{
11 duckdb_aggregate_function_get_extra_info, duckdb_aggregate_function_set_error,
12 duckdb_function_info,
13};
14
15/// What [`AggregateFunctionInfo::set_error`] reports when given an empty
16/// message: `DuckDB` would otherwise show only an error-type prefix such as
17/// `Invalid Input Error: `.
18pub const EMPTY_ERROR_PLACEHOLDER: &str = "aggregate function reported an error without a message";
19
20/// Ergonomic wrapper around the `duckdb_function_info` handle provided to
21/// aggregate function callbacks (update, combine, finalize, etc.).
22///
23/// Provides access to extra info and error reporting.
24pub struct AggregateFunctionInfo {
25 info: duckdb_function_info,
26}
27
28impl AggregateFunctionInfo {
29 /// Wraps a raw `duckdb_function_info` provided by `DuckDB` inside an
30 /// aggregate function callback.
31 ///
32 /// # Safety
33 ///
34 /// `info` must be a valid `duckdb_function_info` passed by `DuckDB` to an
35 /// aggregate function callback.
36 #[inline]
37 #[must_use]
38 pub const unsafe fn new(info: duckdb_function_info) -> Self {
39 Self { info }
40 }
41
42 /// Retrieves the extra-info pointer previously set via
43 /// [`AggregateFunctionBuilder::extra_info`][crate::aggregate::AggregateFunctionBuilder::extra_info].
44 ///
45 /// Returns a raw `*mut c_void`. Cast it back to your concrete type.
46 ///
47 /// # Safety
48 ///
49 /// The returned pointer is only valid as long as the aggregate function is
50 /// registered and `DuckDB` has not yet called the destructor.
51 #[must_use]
52 pub unsafe fn get_extra_info(&self) -> *mut c_void {
53 // SAFETY: self.info is valid per constructor contract.
54 unsafe { duckdb_aggregate_function_get_extra_info(self.info) }
55 }
56
57 /// Borrows the extra info set with `extra_info_typed` (on
58 /// [`AggregateFunctionBuilder`][crate::aggregate::AggregateFunctionBuilder::extra_info_typed]
59 /// or [`AggregateOverloadBuilder`][crate::aggregate::AggregateOverloadBuilder::extra_info_typed])
60 /// as a `T`; `None` when none was set or it holds another type.
61 ///
62 /// # Safety
63 ///
64 /// This function's extra info, if any, was set through `extra_info_typed`
65 /// and not through the raw `extra_info`: the type tag read here is the
66 /// one `extra_info_typed` writes, and a raw pointer carries none.
67 // One FFI call (`get_extra_info`) then the tag check, whose mutants
68 // `extra_info::typed_tests` kill; the `-> None` mutant needs a live engine.
69 #[cfg_attr(test, mutants::skip)]
70 #[must_use]
71 pub unsafe fn extra_info_ref<T: 'static>(&self) -> Option<&T> {
72 // SAFETY: the pointer is null or tagged (this method's contract);
73 // DuckDB keeps it alive while the function is registered, which
74 // outlasts this callback and so `&self`.
75 unsafe { crate::extra_info::tagged_ref(self.get_extra_info()) }
76 }
77
78 /// Reports an error from an aggregate function callback, causing `DuckDB`
79 /// to abort the current query.
80 ///
81 /// An interior NUL byte in `message` is replaced with `?`
82 /// (see [`message_to_c_string`][crate::callback::message_to_c_string]),
83 /// and an empty message by [`EMPTY_ERROR_PLACEHOLDER`], since `DuckDB`
84 /// would otherwise report only an error-type prefix.
85 ///
86 /// Called from `finalize`, the query fails but `DuckDB` does not destroy
87 /// every aggregate state it created, so whatever those states own (an
88 /// [`FfiState`][crate::aggregate::FfiState] box, for one) leaks. That
89 /// holds for a grouped aggregate on every release up to 2.0.0, and for an
90 /// ungrouped one before 2.0.0, which plans a C API aggregate as a hash
91 /// aggregate; 2.0.0 runs an ungrouped aggregate in
92 /// `PhysicalUngroupedAggregate`, which destroys its states. See Known
93 /// Limitations in the book.
94 #[cfg_attr(test, mutants::skip)]
95 pub fn set_error(&self, message: &str) {
96 let c_msg = crate::table::cstr::error_cstring(message, EMPTY_ERROR_PLACEHOLDER);
97 // SAFETY: self.info is valid per constructor contract.
98 unsafe {
99 duckdb_aggregate_function_set_error(self.info, c_msg.as_ptr());
100 }
101 }
102
103 /// Returns the raw `duckdb_function_info` handle.
104 #[must_use]
105 #[inline]
106 pub const fn as_raw(&self) -> duckdb_function_info {
107 self.info
108 }
109}
110
111crate::debug_repr::impl_handle_debug!(AggregateFunctionInfo.info);