Skip to main content

quack_rs/aggregate/
callbacks.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//! Type aliases for the five required `DuckDB` aggregate callback signatures.
7//!
8//! Import these type aliases when defining your callback functions to ensure
9//! you use the correct signature. A mismatch in any parameter type is a silent
10//! bug that is extremely difficult to debug.
11//!
12//! # The five required callbacks
13//!
14//! Every `DuckDB` aggregate function requires exactly these five callbacks
15//! (plus an optional `Destructor`):
16//!
17//! | Callback | When called | Purpose |
18//! |----------|-------------|---------|
19//! | [`StateSizeFn`] | Whenever an operator sizes its state buffers — at least once per query that uses the aggregate, never at registration | Returns `sizeof(FfiState)` in bytes; must return the same value every time |
20//! | [`StateInitFn`] | Per state allocation, including every `combine` target | Initializes a fresh state |
21//! | [`UpdateFn`] | Per batch of input rows | Accumulates data from a chunk into the states |
22//! | [`CombineFn`] | Parallel merge, window segment trees | Merges source states into target states |
23//! | [`FinalizeFn`] | Per batch of result rows, with a `count` and an `offset` | Writes results from `count` states to the output vector starting at `offset` |
24//! | [`DestroyFn`] | After finalize, on the source states once `combine` has merged them, and, after a failed `state_init`, on states that were never initialised; not on some states a stopped scan (or, before `DuckDB` 2.0.0, an `EXCLUDE` window frame) leaves behind (see [`DestroyFn`]) | Frees per-state memory |
25//!
26//! Sources (`DuckDB` 1.5.5): `CAPIAggregateStateSize`, `CAPIAggregateFinalize`
27//! and `CAPIAggregateDestructor` in `src/main/capi/aggregate_function-c.cpp`;
28//! the state-size calls in `aggregate_object.cpp`,
29//! `physical_ungrouped_aggregate.cpp` and the window executors; and
30//! `LocalUngroupedAggregateState`, whose states are destroyed after
31//! `GlobalUngroupedAggregateState::Combine` has merged them
32//! (`physical_ungrouped_aggregate.cpp`).
33//!
34//! # Important: Array-of-pointers calling convention
35//!
36//! The `update`, `combine`, and `finalize` callbacks receive
37//! `*mut duckdb_aggregate_state` — a pointer to an **array** of state pointers.
38//!
39//! # Pitfall: COMBINE must propagate ALL config fields
40//!
41//! See the crate-level documentation for a worked example of this critical bug.
42//!
43//! # Example
44//!
45//! ```rust
46//! use quack_rs::aggregate::callbacks::{StateSizeFn, StateInitFn, UpdateFn, CombineFn, FinalizeFn, DestroyFn};
47//! use libduckdb_sys::{duckdb_function_info, duckdb_aggregate_state, duckdb_data_chunk, duckdb_vector, idx_t};
48//!
49//! unsafe extern "C" fn my_state_size(_: duckdb_function_info) -> idx_t { 8 }
50//! unsafe extern "C" fn my_init(_: duckdb_function_info, _: duckdb_aggregate_state) {}
51//! unsafe extern "C" fn my_update(_: duckdb_function_info, _: duckdb_data_chunk, _: *mut duckdb_aggregate_state) {}
52//! unsafe extern "C" fn my_combine(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: *mut duckdb_aggregate_state, _: idx_t) {}
53//! unsafe extern "C" fn my_finalize(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: duckdb_vector, _: idx_t, _: idx_t) {}
54//! unsafe extern "C" fn my_destroy(_: *mut duckdb_aggregate_state, _: idx_t) {}
55//!
56//! let _: StateSizeFn = my_state_size;
57//! let _: StateInitFn = my_init;
58//! let _: UpdateFn = my_update;
59//! let _: CombineFn = my_combine;
60//! let _: FinalizeFn = my_finalize;
61//! let _: DestroyFn = my_destroy;
62//! ```
63
64use libduckdb_sys::{
65    duckdb_aggregate_state, duckdb_data_chunk, duckdb_function_info, duckdb_vector, idx_t,
66};
67
68/// Returns the size of the aggregate state struct in bytes.
69///
70/// # Example
71///
72/// ```rust
73/// use quack_rs::aggregate::callbacks::StateSizeFn;
74/// use libduckdb_sys::{duckdb_function_info, idx_t};
75///
76/// unsafe extern "C" fn state_size(_: duckdb_function_info) -> idx_t {
77///     std::mem::size_of::<u64>() as idx_t
78/// }
79/// let _: StateSizeFn = state_size;
80/// ```
81pub type StateSizeFn = unsafe extern "C" fn(info: duckdb_function_info) -> idx_t;
82
83/// Initializes a freshly allocated aggregate state.
84///
85/// The `state` parameter is a single `duckdb_aggregate_state` for this group.
86///
87/// # Example
88///
89/// ```rust
90/// use quack_rs::aggregate::callbacks::StateInitFn;
91/// use libduckdb_sys::{duckdb_function_info, duckdb_aggregate_state};
92///
93/// unsafe extern "C" fn state_init(_: duckdb_function_info, _state: duckdb_aggregate_state) {}
94/// let _: StateInitFn = state_init;
95/// ```
96pub type StateInitFn =
97    unsafe extern "C" fn(info: duckdb_function_info, state: duckdb_aggregate_state);
98
99/// Accumulates data from a chunk into the aggregate states.
100///
101/// `states` is a pointer to an array of state pointers — one per **input row**
102/// (rows of the same group carry the same pointer), so `states[row]` is the
103/// state for row `row` of `input`.
104///
105/// The chunk holds **every** input row, NULL rows included, whatever
106/// [`NullHandling`][crate::types::NullHandling] the aggregate was registered
107/// with: check [`VectorReader::is_valid`][crate::vector::VectorReader::is_valid]
108/// before reading a value.
109pub type UpdateFn = unsafe extern "C" fn(
110    info: duckdb_function_info,
111    input: duckdb_data_chunk,
112    states: *mut duckdb_aggregate_state,
113);
114
115/// Merges source states into target states.
116///
117/// Both `source` and `target` point to arrays of `count` state pointers.
118///
119/// # Pitfall L1: Combine must propagate ALL config fields
120///
121/// A `target` state is not a copy of anything: it was set up by your
122/// [`StateInitFn`] (for [`FfiState<T>`][crate::aggregate::FfiState], that is
123/// `T::default()`) and may have seen no `update` at all. All configuration
124/// fields must be copied from `source`, not just accumulated data values.
125///
126/// # Leave `source` unchanged
127///
128/// Read the `source` states; do not modify them. A window's segment tree
129/// combines one of its shared node states into every frame that covers it,
130/// from several threads at once (`WindowSegmentTreePart::WindowSegmentValue`
131/// and `FlushStates`, `window_segment_tree.cpp`), so
132/// a `combine` that consumes its source is right for the first frame that
133/// reads it and wrong for the rest: a sum that moved its value out gave 4985
134/// of 5000 rows wrong over `ROWS BETWEEN 100 PRECEDING AND CURRENT ROW` in
135/// the fifth audit's regression test. Writing to a source another thread is
136/// reading is also a data race. Copy or clone what the target needs.
137///
138/// After `combine` returns, `DuckDB` may call [`DestroyFn`] on the `source`
139/// states, so do not keep pointers into them either.
140pub type CombineFn = unsafe extern "C" fn(
141    info: duckdb_function_info,
142    source: *mut duckdb_aggregate_state,
143    target: *mut duckdb_aggregate_state,
144    count: idx_t,
145);
146
147/// Writes final results from aggregate states to the output vector.
148///
149/// `source` points to an array of `count` state pointers.
150/// Write `count` results starting at `offset` in the output vector.
151///
152/// # NULL output — Pitfall L4
153///
154/// Call `duckdb_vector_ensure_validity_writable` before `duckdb_vector_get_validity`
155/// when writing NULL values, or use [`VectorWriter::set_null`][crate::vector::VectorWriter::set_null].
156pub type FinalizeFn = unsafe extern "C" fn(
157    info: duckdb_function_info,
158    source: *mut duckdb_aggregate_state,
159    result: duckdb_vector,
160    count: idx_t,
161    offset: idx_t,
162);
163
164/// Frees memory allocated by [`StateInitFn`].
165///
166/// Called after finalize, on the source states of a [`CombineFn`] once they
167/// have been merged, and on states that are never finalized. Must free all
168/// heap allocations made in `StateInitFn`.
169///
170/// `DuckDB` does not call it for every state it created: not for a grouped
171/// aggregate's states a stopped result scan never reached
172/// (`docs/upstream-duckdb-reports.md`, item 20; 1.4.4 to 2.0.0), and, before
173/// 2.0.0, not for the states a window frame with `EXCLUDE` initialises for
174/// each row (item 35; fixed in 2.0.0). What those states own on the heap
175/// leaks.
176///
177/// # Not every state it receives was initialised
178///
179/// When a [`StateInitFn`] call fails, `DuckDB` 1.4.4 to 1.5.5 (not re-measured
180/// on 1.5.6) still destroys
181/// every state row it had created, including rows whose `state_init` never ran
182/// — for this aggregate and for any other in the same query
183/// (`RowOperations::InitializeStates` is not exception-safe). In one run
184/// against 1.5.5, a failure at init call 3001 sent 4096 states to the
185/// destructor, 1096 of them never initialised. A destructor that frees a
186/// pointer stored by `state_init` must therefore recognise a slot `state_init`
187/// did not write; [`FfiState`][crate::aggregate::FfiState] does so with a tag.
188/// The same failure also leaves most initialised states undestroyed, so what
189/// they own leaks; see `docs/upstream-duckdb-reports.md`. A failed `finalize`
190/// leaves states undestroyed too: in a grouped query on every release up to
191/// 2.0.0, and in an ungrouped one before 2.0.0 (see
192/// [`AggregateFunctionInfo::set_error`][crate::aggregate::AggregateFunctionInfo::set_error]).
193pub type DestroyFn = unsafe extern "C" fn(states: *mut duckdb_aggregate_state, count: idx_t);
194
195/// The destructor registered for an aggregate whose builder was given none.
196///
197/// It does nothing, and it exists for its presence: `DuckDB` evaluates an
198/// aggregate with **no** state destructor as a *streaming* window
199/// (`PhysicalStreamingWindow::IsStreamingFunction`) for
200/// `agg(x) OVER (ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)` and other
201/// running frames, and that path gives every C API aggregate wrong answers:
202/// it slices the argument chunk to one row per `update` call, and
203/// `CAPIAggregateUpdate` flattens that slice in place on the first call, so
204/// every later row of the chunk re-reads row 0 (Pitfall L13). Any destructor
205/// takes the aggregate off that path. A no-op cannot fail, touches no state
206/// and cannot unwind.
207///
208/// # Safety
209///
210/// None: it reads neither argument. It is `unsafe` only because `DuckDB`'s
211/// destructor slot takes an `unsafe extern "C" fn`.
212pub(crate) const unsafe extern "C" fn no_op_destroy(
213    _states: *mut duckdb_aggregate_state,
214    _count: idx_t,
215) {
216}
217
218#[cfg(test)]
219mod tests {
220    use super::*;
221
222    unsafe extern "C" fn stub_state_size(_: duckdb_function_info) -> idx_t {
223        0
224    }
225    unsafe extern "C" fn stub_state_init(_: duckdb_function_info, _: duckdb_aggregate_state) {}
226    unsafe extern "C" fn stub_update(
227        _: duckdb_function_info,
228        _: duckdb_data_chunk,
229        _: *mut duckdb_aggregate_state,
230    ) {
231    }
232    unsafe extern "C" fn stub_combine(
233        _: duckdb_function_info,
234        _: *mut duckdb_aggregate_state,
235        _: *mut duckdb_aggregate_state,
236        _: idx_t,
237    ) {
238    }
239    unsafe extern "C" fn stub_finalize(
240        _: duckdb_function_info,
241        _: *mut duckdb_aggregate_state,
242        _: duckdb_vector,
243        _: idx_t,
244        _: idx_t,
245    ) {
246    }
247    unsafe extern "C" fn stub_destroy(_: *mut duckdb_aggregate_state, _: idx_t) {}
248
249    #[test]
250    fn all_callback_types_compile() {
251        let _: StateSizeFn = stub_state_size;
252        let _: StateInitFn = stub_state_init;
253        let _: UpdateFn = stub_update;
254        let _: CombineFn = stub_combine;
255        let _: FinalizeFn = stub_finalize;
256        let _: DestroyFn = stub_destroy;
257    }
258}