Implement AbiQueue

Author: Adrian Willenbücher

src/abi_datatypes/src/lib.rs

@@ -15,8 +15,11 @@
 
 extern crate alloc;
 
+mod queue;
 mod storage;
 mod vec;
 
+pub use self::queue::AbiQueue;
+pub use self::queue::FixedQueue;
 pub use self::vec::AbiVec;
 pub use self::vec::FixedVec;

src/abi_datatypes/src/queue.rs

@@ -0,0 +1,289 @@
+// *******************************************************************************
+// Copyright (c) 2025 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Apache License Version 2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// SPDX-License-Identifier: Apache-2.0
+// *******************************************************************************
+
+mod generic;
+
+use core::mem::needs_drop;
+use core::ops;
+
+use self::generic::GenericQueue;
+use crate::storage::Heap;
+use crate::storage::Inline;
+
+/// A fixed-capacity, ABI-compatible queue.
+///
+/// The queue can hold between 0 and `CAPACITY` elements, and behaves similarly to Rust's `VecDeque`,
+/// except that it stores the elements inline and doesn't allocate.
+///
+/// `CAPACITY` must be `>= 1` and `<= u32::MAX`.
+#[repr(transparent)]
+pub struct AbiQueue<T: Copy, const CAPACITY: usize> {
+    inner: GenericQueue<T, Inline<T, CAPACITY>>,
+}
+
+impl<T: Copy, const CAPACITY: usize> AbiQueue<T, CAPACITY> {
+    const CHECK_CAPACITY: () = assert!(0 < CAPACITY && CAPACITY <= u32::MAX as usize);
+
+    /// Creates an empty queue.
+    #[must_use]
+    pub fn new() -> Self {
+        let () = Self::CHECK_CAPACITY;
+
+        Self {
+            inner: GenericQueue::new(CAPACITY as u32),
+        }
+    }
+}
+
+impl<T: Copy, const CAPACITY: usize> Default for AbiQueue<T, CAPACITY> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl<T: Copy, const CAPACITY: usize> ops::Deref for AbiQueue<T, CAPACITY> {
+    type Target = GenericQueue<T, Inline<T, CAPACITY>>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.inner
+    }
+}
+
+impl<T: Copy, const CAPACITY: usize> ops::DerefMut for AbiQueue<T, CAPACITY> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.inner
+    }
+}
+
+/// A fixed-capacity vector.
+///
+/// The vector can hold between 0 and `CAPACITY` elements, and behaves similarly to Rust's `Vec`,
+/// except that it allocates memory immediately on construction, and can't shrink or grow.
+pub struct FixedQueue<T> {
+    inner: GenericQueue<T, Heap<T>>,
+}
+
+impl<T> FixedQueue<T> {
+    /// Creates an empty queue and allocates memory for up to `capacity` elements, where `capacity <= u32::MAX`.
+    ///
+    /// # Panics
+    ///
+    /// - Panics if `capacity > u32::MAX`.
+    /// - Panics if the memory allocation fails.
+    #[must_use]
+    pub fn new(capacity: usize) -> Self {
+        assert!(capacity <= u32::MAX as usize, "FixedQueue can hold at most u32::MAX elements");
+        Self {
+            inner: GenericQueue::new(capacity as u32),
+        }
+    }
+}
+
+impl<T> Drop for FixedQueue<T> {
+    fn drop(&mut self) {
+        if needs_drop::<T>() {
+            self.inner.clear();
+        }
+    }
+}
+
+impl<T> ops::Deref for FixedQueue<T> {
+    type Target = GenericQueue<T, Heap<T>>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.inner
+    }
+}
+
+impl<T> ops::DerefMut for FixedQueue<T> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.inner
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::collections::VecDeque;
+
+    use super::*;
+
+    fn to_vec<T: Copy>((first, second): (&[T], &[T])) -> Vec<T> {
+        let mut elements = first.to_vec();
+        elements.extend_from_slice(second);
+        elements
+    }
+
+    #[test]
+    fn abi_queue_push_and_pop() {
+        fn run_test<const N: usize>() {
+            let mut queue = AbiQueue::<i64, N>::new();
+            let mut control = VecDeque::new();
+
+            // Completely fill and empty the queue N times, but move the internal start point
+            // ahead by one each time
+            for _ in 0..N {
+                let result = queue.pop_front();
+                assert_eq!(result, None);
+
+                for i in 0..N {
+                    let value = i as i64 * 123 + 456;
+                    let result = queue.push_back(value);
+                    assert_eq!(*result.unwrap(), value);
+                    control.push_back(value);
+                    assert_eq!(to_vec(queue.as_slices()), to_vec(control.as_slices()));
+                }
+
+                let result = queue.push_back(123456);
+                assert!(result.is_err());
+
+                for _ in 0..N {
+                    let expected = control.pop_front().unwrap();
+                    let actual = queue.pop_front();
+                    assert_eq!(actual, Some(expected));
+                }
+
+                let result = queue.pop_front();
+                assert_eq!(result, None);
+
+                // One push and one pop to move the internal start point ahead
+                queue.push_back(987).unwrap();
+                assert_eq!(queue.pop_front(), Some(987));
+            }
+        }
+
+        run_test::<1>();
+        run_test::<2>();
+        run_test::<3>();
+        run_test::<4>();
+        run_test::<5>();
+    }
+
+    #[test]
+    fn abi_queue_is_empty_and_is_full() {
+        fn run_test<const N: usize>() {
+            let mut queue = AbiQueue::<i64, N>::new();
+
+            // Completely fill and empty the queue N times, but move the internal start point
+            // ahead by one each time
+            for _ in 0..N {
+                assert!(queue.is_empty());
+
+                for i in 0..N {
+                    assert!(!queue.is_full());
+                    queue.push_back(i as i64 * 123 + 456).unwrap();
+                    assert!(!queue.is_empty());
+                }
+
+                assert!(queue.is_full());
+
+                for _ in 0..N {
+                    assert!(!queue.is_empty());
+                    queue.pop_front();
+                    assert!(!queue.is_full());
+                }
+
+                assert!(queue.is_empty());
+
+                // One push and one pop to move the internal start point ahead
+                queue.push_back(987).unwrap();
+                assert_eq!(queue.pop_front(), Some(987));
+            }
+        }
+
+        run_test::<1>();
+        run_test::<2>();
+        run_test::<3>();
+        run_test::<4>();
+        run_test::<5>();
+    }
+
+    #[test]
+    fn fixed_queue_push_and_pop() {
+        fn run_test(n: usize) {
+            let mut queue = FixedQueue::<i64>::new(n);
+            let mut control = VecDeque::new();
+
+            // Completely fill and empty the queue n times, but move the internal start point
+            // ahead by one each time
+            for _ in 0..n {
+                let result = queue.pop_front();
+                assert_eq!(result, None);
+
+                for i in 0..n {
+                    let value = i as i64 * 123 + 456;
+                    let result = queue.push_back(value);
+                    assert_eq!(*result.unwrap(), value);
+                    control.push_back(value);
+                    assert_eq!(to_vec(queue.as_slices()), to_vec(control.as_slices()));
+                }
+
+                let result = queue.push_back(123456);
+                assert!(result.is_err());
+
+                for _ in 0..n {
+                    let expected = control.pop_front().unwrap();
+                    let actual = queue.pop_front();
+                    assert_eq!(actual, Some(expected));
+                }
+
+                let result = queue.pop_front();
+                assert_eq!(result, None);
+
+                // One push and one pop to move the internal start point ahead
+                queue.push_back(987).unwrap();
+                assert_eq!(queue.pop_front(), Some(987));
+            }
+        }
+
+        for i in 0..6 {
+            run_test(i);
+        }
+    }
+
+    #[test]
+    fn fixed_queue_is_empty_and_is_full() {
+        fn run_test(n: usize) {
+            let mut queue = FixedQueue::<i64>::new(n);
+
+            // Completely fill and empty the queue n times, but move the internal start point
+            // ahead by one each time
+            for _ in 0..n {
+                assert!(queue.is_empty());
+
+                for i in 0..n {
+                    assert!(!queue.is_full());
+                    queue.push_back(i as i64 * 123 + 456).unwrap();
+                    assert!(!queue.is_empty());
+                }
+
+                assert!(queue.is_full());
+
+                for _ in 0..n {
+                    assert!(!queue.is_empty());
+                    queue.pop_front();
+                    assert!(!queue.is_full());
+                }
+
+                assert!(queue.is_empty());
+
+                // One push and one pop to move the internal start point ahead
+                queue.push_back(987).unwrap();
+                assert_eq!(queue.pop_front(), Some(987));
+            }
+        }
+
+        for i in 0..6 {
+            run_test(i);
+        }
+    }
+}