Skip to main content

tea_kernel/
queue.rs

1use std::collections::VecDeque;
2use std::sync::Mutex;
3
4use tea_protocol::{CanonicalMessage, CommandText, MessageRole};
5
6use crate::{KernelError, KernelErrorCode};
7
8/// Thread-safe bounded steering and follow-up queue applied between turns.
9#[derive(Debug)]
10pub struct KernelInputQueue {
11    max_messages: usize,
12    max_steering_bytes: usize,
13    state: Mutex<QueueState>,
14}
15
16#[derive(Debug, Clone, Default)]
17struct QueueState {
18    follow_ups: VecDeque<CanonicalMessage>,
19    steering: Vec<CommandText>,
20    steering_bytes: usize,
21}
22
23#[derive(Debug, Clone)]
24pub(crate) struct QueueSnapshot {
25    pub(crate) follow_ups: Vec<CanonicalMessage>,
26    pub(crate) steering: Vec<CommandText>,
27}
28
29impl KernelInputQueue {
30    /// Creates an empty bounded queue.
31    ///
32    /// # Errors
33    ///
34    /// Returns an error when either limit is zero or unsupported.
35    pub fn new(max_messages: usize, max_steering_bytes: usize) -> Result<Self, KernelError> {
36        if max_messages == 0
37            || max_messages > 1024
38            || max_steering_bytes == 0
39            || max_steering_bytes > 1024 * 1024
40        {
41            return Err(KernelError::new(
42                KernelErrorCode::InvalidRequest,
43                "kernel input queue limits are invalid",
44            ));
45        }
46        Ok(Self {
47            max_messages,
48            max_steering_bytes,
49            state: Mutex::new(QueueState::default()),
50        })
51    }
52
53    /// Appends one canonical user follow-up in FIFO order.
54    ///
55    /// # Errors
56    ///
57    /// Returns an error for a non-user message, queue overflow, or poisoned state.
58    pub fn enqueue_follow_up(&self, message: CanonicalMessage) -> Result<(), KernelError> {
59        if message.role() != MessageRole::User {
60            return Err(KernelError::new(
61                KernelErrorCode::InvalidRequest,
62                "follow-up queue accepts only user messages",
63            ));
64        }
65        let mut state = self.lock()?;
66        if state.follow_ups.len() >= self.max_messages {
67            return Err(KernelError::new(
68                KernelErrorCode::LimitExceeded,
69                "follow-up queue is full",
70            ));
71        }
72        state.follow_ups.push_back(message);
73        Ok(())
74    }
75
76    /// Appends bounded steering text for coalescing at the next turn boundary.
77    ///
78    /// # Errors
79    ///
80    /// Returns an error when accumulated steering exceeds the byte or message limit.
81    pub fn enqueue_steering(&self, text: CommandText) -> Result<(), KernelError> {
82        let mut state = self.lock()?;
83        let bytes = state
84            .steering_bytes
85            .checked_add(text.as_str().len())
86            .and_then(|value| value.checked_add(1))
87            .ok_or_else(queue_overflow)?;
88        if state.steering.len() >= self.max_messages || bytes > self.max_steering_bytes {
89            return Err(queue_overflow());
90        }
91        state.steering.push(text);
92        state.steering_bytes = bytes;
93        Ok(())
94    }
95
96    /// Returns accepted follow-up and steering counts.
97    ///
98    /// # Errors
99    ///
100    /// Returns an error when synchronized state is poisoned.
101    pub fn lengths(&self) -> Result<(usize, usize), KernelError> {
102        let state = self.lock()?;
103        Ok((state.follow_ups.len(), state.steering.len()))
104    }
105
106    pub(crate) fn snapshot(&self) -> Result<QueueSnapshot, KernelError> {
107        let state = self.lock()?;
108        Ok(QueueSnapshot {
109            follow_ups: state.follow_ups.iter().cloned().collect(),
110            steering: state.steering.clone(),
111        })
112    }
113
114    pub(crate) fn acknowledge(&self, snapshot: &QueueSnapshot) -> Result<(), KernelError> {
115        let mut state = self.lock()?;
116        for expected in &snapshot.follow_ups {
117            if state.follow_ups.front() != Some(expected) {
118                return Err(KernelError::new(
119                    KernelErrorCode::InvalidState,
120                    "follow-up queue changed before acknowledgement",
121                ));
122            }
123            state.follow_ups.pop_front();
124        }
125        if state.steering.get(..snapshot.steering.len()) != Some(snapshot.steering.as_slice()) {
126            return Err(KernelError::new(
127                KernelErrorCode::InvalidState,
128                "steering queue changed before acknowledgement",
129            ));
130        }
131        state.steering.drain(..snapshot.steering.len());
132        state.steering_bytes = state
133            .steering
134            .iter()
135            .map(|text| text.as_str().len() + 1)
136            .sum();
137        Ok(())
138    }
139
140    fn lock(&self) -> Result<std::sync::MutexGuard<'_, QueueState>, KernelError> {
141        self.state.lock().map_err(|_| {
142            KernelError::new(
143                KernelErrorCode::InvalidState,
144                "kernel input queue lock is poisoned",
145            )
146        })
147    }
148}
149
150fn queue_overflow() -> KernelError {
151    KernelError::new(
152        KernelErrorCode::LimitExceeded,
153        "steering queue limit was reached",
154    )
155}