Skip to main content

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);