listener_holder/

lib.rs

//! A thread-safe holder for an optional listener (single observer).
//!
//! Use this when you have one optional callback/listener that may be set or cleared at runtime,
//! and you want to notify it from any thread without repeating `RwLock<Option<...>>` boilerplate.
//!
//! The implementation uses [arc-swap](https://docs.rs/arc-swap) for a lock-free read path. See
//! the [CONCURRENCY.md](https://github.com/0barman/listener-holder/blob/main/docs/CONCURRENCY.md) document in the repo for a comparison with `RwLock<Option<Arc<L>>>`.
//!
//! # Type requirements
//!
//! `L` must be `Send + Sync` so that the holder can be shared across threads. The holder itself
//! is `Send + Sync` when `L: Send + Sync`.
//!
//! # Memory and dropping
//!
//! The holder stores at most one `Arc<L>`. Calling [`set`](ListenerHolder::set)(`None`) or
//! replacing the listener drops the previous `Arc` (reference count decremented). Dropping the
//! holder drops its current `Arc`. Cloning the holder or [`get`](ListenerHolder::get) clones
//! the `Arc`; the listener is freed when all `Arc` references are dropped. There is no custom
//! [`Drop`] and no intentional leak.
//!
/// Thread-safe holder for a single optional listener of type `L`.
///
/// The listener is stored as `Option<Arc<L>>` in an [ArcSwapOption], so getting and replacing
/// the listener use atomic operations (lock-free). `L` must be `Send + Sync`; the holder is
/// `Send + Sync` when `L` is.
///
/// # Example
///
/// ```rust
/// use listener_holder::ListenerHolder;
/// use std::sync::Arc;
///
/// struct MyListener;
/// impl MyListener {
///     fn on_event(&self, msg: &str) {
///         println!("event: {}", msg);
///     }
/// }
///
/// let holder: ListenerHolder<MyListener> = ListenerHolder::new();
/// holder.set(Some(Arc::new(MyListener)));
///
/// holder.with_listener(|l| l.on_event("hello")); // prints "event: hello"
/// holder.set(None);  // clear
/// holder.with_listener(|l| l.on_event("ignored")); // no-op
/// ```
use arc_swap::ArcSwapOption;
use std::sync::Arc;

#[derive(Default)]
pub struct ListenerHolder<L> {
    inner: ArcSwapOption<L>,
}

impl<L> ListenerHolder<L>
where
    L: Send + Sync,
{
    /// Creates a new holder with no listener.
    pub fn new() -> Self {
        Self {
            inner: ArcSwapOption::from(None),
        }
    }

    /// Sets or clears the listener. Pass `Some(arc)` to set, `None` to clear.
    pub fn set(&self, listener: Option<Arc<L>>) {
        self.inner.store(listener);
    }

    /// If a listener is present, calls `f` with a reference to it and returns `Some(result)`.
    /// If no listener is set, returns `None` without calling `f`.
    ///
    /// The current listener is loaded with a lock-free atomic load; the closure runs without
    /// holding any lock. If the closure panics, the holder is left unchanged and other threads
    /// can continue to use it.
    pub fn with_listener<F, R>(&self, f: F) -> Option<R>
    where
        F: FnOnce(&L) -> R,
    {
        let guard = self.inner.load();
        let arc = guard.as_ref()?;
        Some(f(arc.as_ref()))
    }

    /// Returns a clone of the current listener's `Arc`, or `None` if none is set.
    ///
    /// The returned `Arc` keeps the listener alive until it is dropped, even if the holder
    /// is later cleared. Useful when you need to call the listener outside the holder
    /// (e.g. in an async context).
    pub fn get(&self) -> Option<Arc<L>> {
        self.inner.load_full()
    }
}

impl<L> std::fmt::Debug for ListenerHolder<L> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ListenerHolder").finish_non_exhaustive()
    }
}

impl<L> Clone for ListenerHolder<L> {
    /// Clones the holder; the clone gets a snapshot of the current listener at the time of
    /// cloning. Subsequent [`set`](ListenerHolder::set) calls on either holder do not affect
    /// the other.
    fn clone(&self) -> Self {
        let current = self.inner.load_full();
        Self {
            inner: ArcSwapOption::from(current),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::sync::atomic::{AtomicU32, Ordering};

    #[derive(Default)]
    struct Counter {
        count: AtomicU32,
    }
    impl Counter {
        fn add(&self, n: u32) {
            self.count.fetch_add(n, Ordering::SeqCst);
        }
        fn get(&self) -> u32 {
            self.count.load(Ordering::SeqCst)
        }
    }

    #[test]
    fn set_and_with_listener() {
        let holder: ListenerHolder<Counter> = ListenerHolder::new();
        assert!(holder.with_listener(|c| c.get()).is_none());

        let c = Arc::new(Counter::default());
        holder.set(Some(c.clone()));
        holder.with_listener(|l| l.add(1));
        holder.with_listener(|l| l.add(2));
        assert_eq!(c.get(), 3);

        holder.set(None);
        assert!(holder.with_listener(|c| c.get()).is_none());
        assert_eq!(c.get(), 3);
    }

    #[test]
    fn get_returns_clone() {
        let holder: ListenerHolder<Counter> = ListenerHolder::new();
        let c = Arc::new(Counter::default());
        holder.set(Some(c.clone()));
        let out = holder.get().unwrap();
        out.add(1);
        assert_eq!(c.get(), 1);
    }

    #[test]
    fn clone_holder_copies_listener() {
        let a = ListenerHolder::new();
        a.set(Some(Arc::new(Counter::default())));
        let b = a.clone();
        a.set(None);
        assert!(a.with_listener(|_| ()).is_none());
        assert!(b.with_listener(|c| c.get()).is_some());
    }

    #[test]
    fn with_listener_panic_does_not_poison_holder() {
        let holder: ListenerHolder<Counter> = ListenerHolder::new();
        holder.set(Some(Arc::new(Counter::default())));
        // 临时取消 panic hook，避免预期的 panic 被打印到 stderr
        let prev = std::panic::take_hook();
        std::panic::set_hook(Box::new(|_| {}));
        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            holder.with_listener(|_| panic!("test panic"));
        }));
        std::panic::set_hook(prev);
        assert!(result.is_err()); // 确认发生了 panic
                                  // Holder still usable; listener still set
        assert!(holder.with_listener(|c| c.get()).is_some());
    }
}