dynomite-engine 1.1.0

//! Message-id to message lookup.
//!
//! A per-connection lookup keyed on `MsgId` pairs a response
//! arriving on the wire with its outstanding request in constant
//! time. [`crate::util::dict::MsgIndex`] (an `ahash`-backed
//! [`std::collections::HashMap`]) keyed on [`MsgId`] provides the
//! message-flavored alias plus a thin newtype that adds
//! the verbs the message layer actually uses.
//!
//! [`MsgId`]: crate::core::types::MsgId

use crate::core::types::MsgId;
use crate::util::dict::DictMap;

use super::message::Msg;

/// Owning index of [`Msg`] values keyed on [`MsgId`].
///
/// The index owns each [`Msg`] value directly, so dropping the index
/// releases every contained message. Lookups return references;
/// transferring ownership out of the index requires
/// [`MsgIndex::remove`].
///
/// # Thread safety
///
/// `MsgIndex` is per-connection and accessed only from the
/// connection's owning event-loop thread. It honours that
/// single-threaded contract: `MsgIndex` is `Send` (it can be moved
/// to another task or thread, e.g. when a connection migrates) but
/// is intentionally not exposed through any synchronisation
/// primitive. The wrapped [`std::collections::HashMap`] inside
/// [`DictMap`] is not `Sync`, so two
/// tasks cannot share a `&MsgIndex` and call its mutating methods
/// concurrently. Stages 9 and beyond keep the index private to the
/// per-connection FSM; if a future caller ever needs cross-thread
/// shared access, that caller is responsible for wrapping it in a
/// `Mutex` (or equivalent), not the type itself.
#[derive(Debug)]
pub struct MsgIndex {
    inner: DictMap<MsgId, Msg>,
}

impl Default for MsgIndex {
    fn default() -> Self {
        Self {
            inner: DictMap::new(),
        }
    }
}

impl MsgIndex {
    /// Build an empty index.
    ///
    /// # Examples
    ///
    /// ```
    /// use dynomite::msg::MsgIndex;
    /// let idx = MsgIndex::new();
    /// assert!(idx.is_empty());
    /// ```
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Insert `msg` under its own id. The previous value, if any, is
    /// returned to the caller.
    ///
    /// # Examples
    ///
    /// ```
    /// use dynomite::msg::{Msg, MsgIndex, MsgType};
    ///
    /// let mut idx = MsgIndex::new();
    /// let m = Msg::new(7, MsgType::ReqRedisGet, true);
    /// assert!(idx.insert(m).is_none());
    /// assert!(idx.contains_key(7));
    /// ```
    pub fn insert(&mut self, msg: Msg) -> Option<Msg> {
        self.inner.insert(msg.id(), msg)
    }

    /// Remove the message stored under `id` and transfer ownership
    /// to the caller.
    ///
    /// # Examples
    ///
    /// ```
    /// use dynomite::msg::{Msg, MsgIndex, MsgType};
    ///
    /// let mut idx = MsgIndex::new();
    /// idx.insert(Msg::new(7, MsgType::ReqRedisGet, true));
    /// assert!(idx.remove(7).is_some());
    /// assert!(idx.remove(7).is_none());
    /// ```
    pub fn remove(&mut self, id: MsgId) -> Option<Msg> {
        self.inner.remove(&id)
    }

    /// Borrow the message stored under `id`, if any.
    ///
    /// # Examples
    ///
    /// ```
    /// use dynomite::msg::{Msg, MsgIndex, MsgType};
    ///
    /// let mut idx = MsgIndex::new();
    /// idx.insert(Msg::new(7, MsgType::ReqRedisGet, true));
    /// assert_eq!(idx.get(7).unwrap().id(), 7);
    /// ```
    #[must_use]
    pub fn get(&self, id: MsgId) -> Option<&Msg> {
        self.inner.get(&id)
    }

    /// Mutably borrow the message stored under `id`.
    ///
    /// # Examples
    ///
    /// ```
    /// use dynomite::msg::{Msg, MsgIndex, MsgType};
    ///
    /// let mut idx = MsgIndex::new();
    /// idx.insert(Msg::new(7, MsgType::ReqRedisGet, true));
    /// idx.get_mut(7).unwrap().set_done(true);
    /// ```
    pub fn get_mut(&mut self, id: MsgId) -> Option<&mut Msg> {
        self.inner.get_mut(&id)
    }

    /// True when an entry exists for `id`.
    ///
    /// # Examples
    ///
    /// ```
    /// use dynomite::msg::MsgIndex;
    /// assert!(!MsgIndex::new().contains_key(0));
    /// ```
    #[must_use]
    pub fn contains_key(&self, id: MsgId) -> bool {
        self.inner.contains_key(&id)
    }

    /// Number of indexed messages.
    ///
    /// # Examples
    ///
    /// ```
    /// use dynomite::msg::MsgIndex;
    /// assert_eq!(MsgIndex::new().len(), 0);
    /// ```
    #[must_use]
    pub fn len(&self) -> usize {
        self.inner.len()
    }

    /// True when the index has no entries.
    ///
    /// # Examples
    ///
    /// ```
    /// use dynomite::msg::MsgIndex;
    /// assert!(MsgIndex::new().is_empty());
    /// ```
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.inner.is_empty()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::msg::{Msg, MsgType};

    #[test]
    fn round_trip() {
        let mut idx = MsgIndex::new();
        let m = Msg::new(42, MsgType::ReqRedisGet, true);
        assert!(idx.insert(m).is_none());
        assert!(idx.contains_key(42));
        let popped = idx.remove(42).expect("present");
        assert_eq!(popped.id(), 42);
        assert!(!idx.contains_key(42));
    }

    #[test]
    fn get_and_get_mut_borrow_the_entry() {
        // get borrows immutably; get_mut allows in-place mutation.
        let mut idx = MsgIndex::new();
        idx.insert(Msg::new(7, MsgType::ReqRedisGet, true));
        assert_eq!(idx.get(7).unwrap().id(), 7);
        assert!(idx.get(8).is_none());
        idx.get_mut(7).unwrap().set_done(true);
        assert!(idx.get(7).unwrap().flags().done);
        assert!(idx.get_mut(8).is_none());
    }

    #[test]
    fn len_and_is_empty_track_population() {
        // len counts entries; is_empty flips once an entry exists.
        let mut idx = MsgIndex::new();
        assert!(idx.is_empty());
        assert_eq!(idx.len(), 0);
        idx.insert(Msg::new(1, MsgType::ReqRedisGet, true));
        assert!(!idx.is_empty());
        assert_eq!(idx.len(), 1);
    }
}