From 74037f04933f4ec9a678e0b47fd6819e7c0489a9 Mon Sep 17 00:00:00 2001
From: Dániel Buga <bugadani@gmail.com>
Date: Mon, 4 Aug 2025 00:05:25 +0200
Subject: Make TimerQueueItem opaque

---
 embassy-executor-timer-queue/src/lib.rs | 97 +++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 embassy-executor-timer-queue/src/lib.rs

(limited to 'embassy-executor-timer-queue/src/lib.rs')

diff --git a/embassy-executor-timer-queue/src/lib.rs b/embassy-executor-timer-queue/src/lib.rs
new file mode 100644
index 000000000..456ccaec3
--- /dev/null
+++ b/embassy-executor-timer-queue/src/lib.rs
@@ -0,0 +1,97 @@
+//! Timer queue item for embassy-executor integrated timer queues
+//!
+//! `embassy-executor` provides the memory needed to implement integrated timer queues. This crate
+//! exists to separate that memory from `embassy-executor` itself, to decouple the timer queue's
+//! release cycle from `embassy-executor`.
+//!
+//! This crate contains two things:
+//! - [`TimerQueueItem`]: The item type that can be requested from the executor. The size of this
+//!   type can be configured using the `timer-item-size-N-words` Cargo features.
+//! - The expectation that `extern "Rust" fn __embassy_time_queue_item_from_waker(waker: &Waker) -> &mut TimerQueueItem`
+//!   is implemented (by `embassy-executor`, most likely). This function must return a mutable
+//!   reference to the `TimerQueueItem` associated with the given waker.
+//!
+//! As a queue implementor, you will need to choose one of the `timer-item-size-N-words` features to
+//! select a queue item size. You can then define your own item type, which must be
+//! `#[repr(align(8))]` (or less) and must fit into the size you selected.
+//!
+//! You can access the `TimerQueueItem` from a `Waker` using the [`from_embassy_waker`](TimerQueueItem::from_embassy_waker)
+//! method. You can then use the [`as_ref`](TimerQueueItem::as_ref) and [`as_mut`](TimerQueueItem::as_mut)
+//! methods to reinterpret the data stored in the item as your custom item type.
+#![no_std]
+
+use core::task::Waker;
+
+const ITEM_SIZE: usize = if cfg!(feature = "timer-item-size-8-words") {
+    8
+} else if cfg!(feature = "timer-item-size-6-words") {
+    6
+} else if cfg!(feature = "timer-item-size-4-words") {
+    4
+} else {
+    0
+};
+
+/// The timer queue item provided by the executor.
+///
+/// This type is opaque, it only provides the raw storage for a queue item. The queue implementation
+/// is responsible for reinterpreting the contents of the item using [`TimerQueueItem::as_ref`] and
+/// [`TimerQueueItem::as_mut`].
+#[repr(align(8))]
+pub struct TimerQueueItem {
+    data: [usize; ITEM_SIZE],
+}
+
+impl TimerQueueItem {
+    /// Creates a new, zero-initialized `TimerQueueItem`.
+    pub const fn new() -> Self {
+        Self { data: [0; ITEM_SIZE] }
+    }
+
+    /// Retrieves the `TimerQueueItem` reference that belongs to the task of the waker.
+    ///
+    /// Panics if called with a non-embassy waker.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure they are not violating Rust's aliasing rules - it is not allowed
+    /// to use this method to create multiple mutable references to the same `TimerQueueItem` at
+    /// the same time.
+    ///
+    /// This function must only be called in the context of a timer queue implementation.
+    pub unsafe fn from_embassy_waker(waker: &Waker) -> &'static mut Self {
+        unsafe extern "Rust" {
+            // Waker -> TimerQueueItem, validates that Waker is an embassy Waker.
+            fn __embassy_time_queue_item_from_waker(waker: &Waker) -> &'static mut TimerQueueItem;
+        }
+        unsafe { __embassy_time_queue_item_from_waker(waker) }
+    }
+
+    /// Access the data as a reference to a type `T`.
+    ///
+    /// Safety:
+    ///
+    /// - The type must be valid when zero-initialized.
+    /// - The timer queue should only be interpreted as a single type `T` during its lifetime.
+    pub unsafe fn as_ref<T>(&self) -> &T {
+        const {
+            assert!(core::mem::size_of::<Self>() >= core::mem::size_of::<T>());
+            assert!(core::mem::align_of::<Self>() >= core::mem::align_of::<T>());
+        }
+        unsafe { &*(self.data.as_ptr() as *const T) }
+    }
+
+    /// Access the data as a reference to a type `T`.
+    ///
+    /// Safety:
+    ///
+    /// - The type must be valid when zero-initialized.
+    /// - The timer queue should only be interpreted as a single type `T` during its lifetime.
+    pub unsafe fn as_mut<T>(&self) -> &mut T {
+        const {
+            assert!(core::mem::size_of::<Self>() >= core::mem::size_of::<T>());
+            assert!(core::mem::align_of::<Self>() >= core::mem::align_of::<T>());
+        }
+        unsafe { &mut *(self.data.as_ptr() as *mut T) }
+    }
+}
-- 
cgit