atomic-bitflags 0.1.1

//! Atomic storage for a [`bitflags`] flag set.
//!
//! [`AtomicFlags<F>`] keeps the bits of a `bitflags` type in an atomic
//! integer, so a flag set can be shared between threads without a lock.
//!
//! Every operation on the stored value takes an [`Ordering`] under the same
//! rules as the standard library atomics. Flags wider than 64 bits are not
//! supported, and 64-bit atomics are not available on every target.
//!
//! # Examples
//!
//! ```
//! use atomic_bitflags::AtomicFlags;
//! use bitflags::bitflags;
//! use std::sync::Arc;
//! use std::sync::atomic::Ordering;
//!
//! bitflags! {
//!     #[derive(Debug, Clone, Copy, PartialEq, Eq)]
//!     struct Features: u8 {
//!         const FAST = 0b001;
//!         const SAFE = 0b010;
//!     }
//! }
//!
//! let flags = Arc::new(AtomicFlags::new(Features::FAST));
//! let remote = Arc::clone(&flags);
//!
//! std::thread::spawn(move || {
//!     remote.set(Features::SAFE, Ordering::Relaxed);
//! })
//! .join()
//! .unwrap();
//!
//! let current = flags.load(Ordering::Relaxed);
//! assert!(current.contains(Features::FAST | Features::SAFE));
//! ```

use std::fmt;
use std::sync::atomic::Ordering;

use bitflags::Flags;

mod atomic_bits;
#[cfg(test)]
mod tests;

pub use atomic_bits::AtomicBits;

/// A flag set stored in an atomic integer.
pub struct AtomicFlags<F>
where
    F: Flags,
    F::Bits: AtomicBits,
    F: Copy,
{
    storage: <F::Bits as AtomicBits>::Storage,
}

impl<F> Default for AtomicFlags<F>
where
    F: Flags,
    F::Bits: AtomicBits,
    F: Copy,
    F: Default,
{
    fn default() -> Self {
        Self::new(F::default())
    }
}

impl<F> fmt::Debug for AtomicFlags<F>
where
    F: Flags,
    F::Bits: AtomicBits,
    F: Copy,
    F: fmt::Debug,
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.load(Ordering::SeqCst).fmt(f)
    }
}

impl<F> AtomicFlags<F>
where
    F: Flags,
    F::Bits: AtomicBits,
    F: Copy,
{
    pub fn new(flags: F) -> Self {
        Self {
            storage: F::Bits::new(flags.bits()),
        }
    }

    pub fn store(&self, flags: F, ordering: Ordering) {
        F::Bits::store(&self.storage, flags.bits(), ordering);
    }

    pub fn load(&self, ordering: Ordering) -> F {
        F::from_bits_retain(F::Bits::load(&self.storage, ordering))
    }

    /// Atomically clears `flags`, returning the previous value.
    pub fn fetch_and(&self, flags: F, ordering: Ordering) -> F {
        F::from_bits_retain(F::Bits::fetch_and(&self.storage, flags.bits(), ordering))
    }

    /// Atomically sets `flags`, returning the previous value.
    pub fn fetch_or(&self, flags: F, ordering: Ordering) -> F {
        F::from_bits_retain(F::Bits::fetch_or(&self.storage, flags.bits(), ordering))
    }

    /// Atomically toggles `flags`, returning the previous value.
    pub fn fetch_xor(&self, flags: F, ordering: Ordering) -> F {
        F::from_bits_retain(F::Bits::fetch_xor(&self.storage, flags.bits(), ordering))
    }

    /// Atomically replaces the value with `!(current & flags)`, returning the
    /// previous value.
    ///
    /// This follows the standard atomic `fetch_nand`: the result is not
    /// restricted to `flags`, so bits outside the mask are set.
    pub fn fetch_nand(&self, flags: F, ordering: Ordering) -> F {
        F::from_bits_retain(F::Bits::fetch_nand(&self.storage, flags.bits(), ordering))
    }

    /// Atomically replaces the value with `flags`, returning the previous value.
    pub fn swap(&self, flags: F, ordering: Ordering) -> F {
        F::from_bits_retain(F::Bits::swap(&self.storage, flags.bits(), ordering))
    }

    /// Atomically clears `flags` and returns the subset that was set.
    ///
    /// Returns an empty set if none of `flags` were set. Other bits are left
    /// untouched.
    pub fn take(&self, flags: F, ordering: Ordering) -> F {
        let previous = self.fetch_and(flags.complement(), ordering);
        previous.intersection(flags)
    }

    /// Returns the subset of `flags` that is currently set.
    ///
    /// Does not modify the stored value. The result is a snapshot from a single
    /// load; use [`take`](Self::take) to claim flags atomically.
    pub fn peek(&self, flags: F, ordering: Ordering) -> F {
        self.load(ordering).intersection(flags)
    }

    /// Clears all flags.
    pub fn clear(&self, ordering: Ordering) {
        self.store(F::empty(), ordering);
    }

    /// Consumes the atomic and returns the flags.
    pub fn into_inner(self) -> F {
        F::from_bits_retain(F::Bits::into_inner(self.storage))
    }

    /// Atomically sets the bits in `flags`, returning the previous value.
    pub fn set(&self, flags: F, ordering: Ordering) -> F {
        self.fetch_or(flags, ordering)
    }

    /// Atomically clears the bits in `flags`, returning the previous value.
    pub fn unset(&self, flags: F, ordering: Ordering) -> F {
        self.fetch_and(flags.complement(), ordering)
    }
}