Skip to main content

uqa_execution/query/
notice_queue.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! The notices a session queues for its client.
8
9use parking_lot::Mutex;
10use std::collections::VecDeque;
11use std::sync::atomic::{AtomicU8, Ordering};
12use std::sync::Arc;
13use uqa_sql::semantics::parameters::catalog::message_levels;
14use uqa_sql::SQLNotice;
15
16/// The notices a session queues for its client, in the order they arrive. A notice below the session's `client_min_messages` is dropped as it arrives, as `PostgreSQL` decides whether a report reaches the client when it raises it (`errstart`), so a level that a function sets for its own body silences only the notices raised there.
17pub struct NoticeQueue {
18    notices: Mutex<VecDeque<SQLNotice>>,
19    /// The session's `client_min_messages`, as a message level, which the session keeps current.
20    client_level: Arc<AtomicU8>,
21}
22
23impl Default for NoticeQueue {
24    fn default() -> Self {
25        Self::new(Arc::new(AtomicU8::new(message_levels::NOTICE)))
26    }
27}
28
29impl NoticeQueue {
30    /// A queue that reads the session's `client_min_messages` from `client_level`.
31    pub fn new(client_level: Arc<AtomicU8>) -> Self {
32        Self {
33            notices: Mutex::new(VecDeque::new()),
34            client_level,
35        }
36    }
37
38    /// Queue `notice` after the notices queued before it, unless its level does not reach the client.
39    pub fn push(&self, notice: SQLNotice) {
40        if notice
41            .level
42            .reaches_client(self.client_level.load(Ordering::Acquire))
43        {
44            self.notices.lock().push_back(notice);
45        }
46    }
47
48    /// Take every queued notice in the order they arrived.
49    pub fn take(&self) -> Vec<SQLNotice> {
50        let notices = std::mem::take(&mut *self.notices.lock());
51        notices.into()
52    }
53
54    /// Admit one transfer before removing the oldest notice. Rejection or unwinding leaves the
55    /// queue unchanged. `prepare` runs under the queue lock and must not reenter the queue or
56    /// execute statements that can emit notices. Success moves the original notice without
57    /// copying its fields or shifting the remaining queue.
58    pub fn try_take_with<T, E>(
59        &self,
60        prepare: impl FnOnce(&SQLNotice) -> Result<T, E>,
61    ) -> Result<Option<(SQLNotice, T)>, E> {
62        let mut notices = self.notices.lock();
63        let Some(notice) = notices.front() else {
64            return Ok(None);
65        };
66        let admitted = prepare(notice)?;
67        Ok(Some((
68            notices.pop_front().expect("admitted notice remains queued"),
69            admitted,
70        )))
71    }
72
73    /// The queued notices, left queued.
74    pub fn snapshot(&self) -> Vec<SQLNotice> {
75        self.notices.lock().iter().cloned().collect()
76    }
77
78    pub fn len(&self) -> usize {
79        self.notices.lock().len()
80    }
81
82    pub fn is_empty(&self) -> bool {
83        self.notices.lock().is_empty()
84    }
85}
86
87#[cfg(test)]
88mod tests;