/rust/registry/src/index.crates.io-1949cf8c6b5b557f/crossbeam-epoch-0.9.20/src/epoch.rs

Source
//! The global epoch
//!
//! The last bit in this number is unused and is always zero. Every so often the global epoch is
//! incremented, i.e. we say it "advances". A pinned participant may advance the global epoch only
//! if all currently pinned participants have been pinned in the current epoch.
//!
//! If an object became garbage in some epoch, then we can be sure that after two advancements no
//! participant will hold a reference to it. That is the crux of safe memory reclamation.

use crate::primitive::sync::atomic::Ordering;

// Ideally, we want to always use AtomicU64, but since it is not available on all platforms,
// we only use it when it is available for now.
// TODO: On platforms where AtomicU64 is unavailable, we may want to use AtomicCell instead of AtomicUsize.
#[cfg(target_has_atomic = "64")]
type AtomicEpochRepr = crate::primitive::sync::atomic::AtomicU64;
#[cfg(not(target_has_atomic = "64"))]
type AtomicEpochRepr = crate::primitive::sync::atomic::AtomicUsize;
#[cfg(target_has_atomic = "64")]
type EpochRepr = u64;
#[cfg(not(target_has_atomic = "64"))]
type EpochRepr = usize;
#[cfg(target_has_atomic = "64")]
type EpochReprSigned = i64;
#[cfg(not(target_has_atomic = "64"))]
type EpochReprSigned = isize;

/// An epoch that can be marked as pinned or unpinned.
///
/// Internally, the epoch is represented as an integer that wraps around at some unspecified point
/// and a flag that represents whether it is pinned or unpinned.
#[derive(Copy, Clone, Default, Debug, Eq, PartialEq)]
pub(crate) struct Epoch {
    /// The least significant bit is set if pinned. The rest of the bits hold the epoch.
    data: EpochRepr,
}

impl Epoch {
    /// Returns the starting epoch in unpinned state.
    #[inline]
    pub(crate) fn starting() -> Self {
        Self::default()
    }

    /// Returns the number of epochs `self` is ahead of `rhs`.
    ///
    /// Internally, epochs are represented as numbers in the range `(isize::MIN / 2) .. (isize::MAX
    /// / 2)`, so the returned distance will be in the same interval.
    pub(crate) fn wrapping_sub(self, rhs: Self) -> EpochReprSigned {
        // The result is the same with `(self.data & !1).wrapping_sub(rhs.data & !1) as isize >> 1`,
        // because the possible difference of LSB in `(self.data & !1).wrapping_sub(rhs.data & !1)`
        // will be ignored in the shift operation.
        self.data.wrapping_sub(rhs.data & !1) as EpochReprSigned >> 1
    }

    /// Returns `true` if the epoch is marked as pinned.
    #[inline]
    pub(crate) fn is_pinned(self) -> bool {
        (self.data & 1) == 1
    }

    /// Returns the same epoch, but marked as pinned.
    #[inline]
    pub(crate) fn pinned(self) -> Epoch {
        Epoch {
            data: self.data | 1,
        }
    }

    /// Returns the same epoch, but marked as unpinned.
    #[inline]
    pub(crate) fn unpinned(self) -> Epoch {
        Epoch {
            data: self.data & !1,
        }
    }

    /// Returns the successor epoch.
    ///
    /// The returned epoch will be marked as pinned only if the previous one was as well.
    #[inline]
    pub(crate) fn successor(self) -> Epoch {
        Epoch {
            data: self.data.wrapping_add(2),
        }
    }
}

/// An atomic value that holds an `Epoch`.
#[derive(Default, Debug)]
pub(crate) struct AtomicEpoch {
    /// Since `Epoch` is just a wrapper around `usize`, an `AtomicEpoch` is similarly represented
    /// using an `AtomicUsize`.
    data: AtomicEpochRepr,
}

impl AtomicEpoch {
    /// Creates a new atomic epoch.
    #[inline]
    pub(crate) fn new(epoch: Epoch) -> Self {
        let data = AtomicEpochRepr::new(epoch.data);
        Self { data }
    }

    /// Loads a value from the atomic epoch.
    #[inline]
    pub(crate) fn load(&self, ord: Ordering) -> Epoch {
        Epoch {
            data: self.data.load(ord),
        }
    }

    /// Stores a value into the atomic epoch.
    #[inline]
    pub(crate) fn store(&self, epoch: Epoch, ord: Ordering) {
        self.data.store(epoch.data, ord);
    }

    /// Stores a value into the atomic epoch if the current value is the same as `current`.
    ///
    /// The return value is a result indicating whether the new value was written and containing
    /// the previous value. On success this value is guaranteed to be equal to `current`.
    ///
    /// This method takes two `Ordering` arguments to describe the memory
    /// ordering of this operation. `success` describes the required ordering for the
    /// read-modify-write operation that takes place if the comparison with `current` succeeds.
    /// `failure` describes the required ordering for the load operation that takes place when
    /// the comparison fails. Using `Acquire` as success ordering makes the store part
    /// of this operation `Relaxed`, and using `Release` makes the successful load
    /// `Relaxed`. The failure ordering can only be `SeqCst`, `Acquire` or `Relaxed`
    /// and must be equivalent to or weaker than the success ordering.
    #[inline]
    pub(crate) fn compare_exchange(
        &self,
        current: Epoch,
        new: Epoch,
        success: Ordering,
        failure: Ordering,
    ) -> Result<Epoch, Epoch> {
        match self
            .data
            .compare_exchange(current.data, new.data, success, failure)
        {
            Ok(data) => Ok(Epoch { data }),
            Err(data) => Err(Epoch { data }),
        }
    }
}

Line	Count	Source
1		//! The global epoch
2		//!
3		//! The last bit in this number is unused and is always zero. Every so often the global epoch is
4		//! incremented, i.e. we say it "advances". A pinned participant may advance the global epoch only
5		//! if all currently pinned participants have been pinned in the current epoch.
6		//!
7		//! If an object became garbage in some epoch, then we can be sure that after two advancements no
8		//! participant will hold a reference to it. That is the crux of safe memory reclamation.
9
10		use crate::primitive::sync::atomic::Ordering;
11
12		// Ideally, we want to always use AtomicU64, but since it is not available on all platforms,
13		// we only use it when it is available for now.
14		// TODO: On platforms where AtomicU64 is unavailable, we may want to use AtomicCell instead of AtomicUsize.
15		#[cfg(target_has_atomic = "64")]
16		type AtomicEpochRepr = crate::primitive::sync::atomic::AtomicU64;
17		#[cfg(not(target_has_atomic = "64"))]
18		type AtomicEpochRepr = crate::primitive::sync::atomic::AtomicUsize;
19		#[cfg(target_has_atomic = "64")]
20		type EpochRepr = u64;
21		#[cfg(not(target_has_atomic = "64"))]
22		type EpochRepr = usize;
23		#[cfg(target_has_atomic = "64")]
24		type EpochReprSigned = i64;
25		#[cfg(not(target_has_atomic = "64"))]
26		type EpochReprSigned = isize;
27
28		/// An epoch that can be marked as pinned or unpinned.
29		///
30		/// Internally, the epoch is represented as an integer that wraps around at some unspecified point
31		/// and a flag that represents whether it is pinned or unpinned.
32		#[derive(Copy, Clone, Default, Debug, Eq, PartialEq)]
33		pub(crate) struct Epoch {
34		/// The least significant bit is set if pinned. The rest of the bits hold the epoch.
35		data: EpochRepr,
36		}
37
38		impl Epoch {
39		/// Returns the starting epoch in unpinned state.
40		#[inline]
41	0	pub(crate) fn starting() -> Self {
42	0	Self::default()
43	0	} Unexecuted instantiation: <crossbeam_epoch::epoch::Epoch>::starting Unexecuted instantiation: <crossbeam_epoch::epoch::Epoch>::starting
44
45		/// Returns the number of epochs `self` is ahead of `rhs`.
46		///
47		/// Internally, epochs are represented as numbers in the range `(isize::MIN / 2) .. (isize::MAX
48		/// / 2)`, so the returned distance will be in the same interval.
49	0	pub(crate) fn wrapping_sub(self, rhs: Self) -> EpochReprSigned {
50		// The result is the same with `(self.data & !1).wrapping_sub(rhs.data & !1) as isize >> 1`,
51		// because the possible difference of LSB in `(self.data & !1).wrapping_sub(rhs.data & !1)`
52		// will be ignored in the shift operation.
53	0	self.data.wrapping_sub(rhs.data & !1) as EpochReprSigned >> 1
54	0	}
55
56		/// Returns `true` if the epoch is marked as pinned.
57		#[inline]
58	0	pub(crate) fn is_pinned(self) -> bool {
59	0	(self.data & 1) == 1
60	0	}
61
62		/// Returns the same epoch, but marked as pinned.
63		#[inline]
64	0	pub(crate) fn pinned(self) -> Epoch {
65	0	Epoch {
66	0	data: self.data \| 1,
67	0	}
68	0	} Unexecuted instantiation: <crossbeam_epoch::epoch::Epoch>::pinned Unexecuted instantiation: <crossbeam_epoch::epoch::Epoch>::pinned
69
70		/// Returns the same epoch, but marked as unpinned.
71		#[inline]
72	0	pub(crate) fn unpinned(self) -> Epoch {
73	0	Epoch {
74	0	data: self.data & !1,
75	0	}
76	0	}
77
78		/// Returns the successor epoch.
79		///
80		/// The returned epoch will be marked as pinned only if the previous one was as well.
81		#[inline]
82	0	pub(crate) fn successor(self) -> Epoch {
83	0	Epoch {
84	0	data: self.data.wrapping_add(2),
85	0	}
86	0	}
87		}
88
89		/// An atomic value that holds an `Epoch`.
90		#[derive(Default, Debug)]
91		pub(crate) struct AtomicEpoch {
92		/// Since `Epoch` is just a wrapper around `usize`, an `AtomicEpoch` is similarly represented
93		/// using an `AtomicUsize`.
94		data: AtomicEpochRepr,
95		}
96
97		impl AtomicEpoch {
98		/// Creates a new atomic epoch.
99		#[inline]
100	0	pub(crate) fn new(epoch: Epoch) -> Self {
101	0	let data = AtomicEpochRepr::new(epoch.data);
102	0	Self { data }
103	0	}
104
105		/// Loads a value from the atomic epoch.
106		#[inline]
107	0	pub(crate) fn load(&self, ord: Ordering) -> Epoch {
108	0	Epoch {
109	0	data: self.data.load(ord),
110	0	}
111	0	} Unexecuted instantiation: <crossbeam_epoch::epoch::AtomicEpoch>::load Unexecuted instantiation: <crossbeam_epoch::epoch::AtomicEpoch>::load
112
113		/// Stores a value into the atomic epoch.
114		#[inline]
115	0	pub(crate) fn store(&self, epoch: Epoch, ord: Ordering) {
116	0	self.data.store(epoch.data, ord);
117	0	}
118
119		/// Stores a value into the atomic epoch if the current value is the same as `current`.
120		///
121		/// The return value is a result indicating whether the new value was written and containing
122		/// the previous value. On success this value is guaranteed to be equal to `current`.
123		///
124		/// This method takes two `Ordering` arguments to describe the memory
125		/// ordering of this operation. `success` describes the required ordering for the
126		/// read-modify-write operation that takes place if the comparison with `current` succeeds.
127		/// `failure` describes the required ordering for the load operation that takes place when
128		/// the comparison fails. Using `Acquire` as success ordering makes the store part
129		/// of this operation `Relaxed`, and using `Release` makes the successful load
130		/// `Relaxed`. The failure ordering can only be `SeqCst`, `Acquire` or `Relaxed`
131		/// and must be equivalent to or weaker than the success ordering.
132		#[inline]
133	0	pub(crate) fn compare_exchange(
134	0	&self,
135	0	current: Epoch,
136	0	new: Epoch,
137	0	success: Ordering,
138	0	failure: Ordering,
139	0	) -> Result<Epoch, Epoch> {
140	0	match self
141	0	.data
142	0	.compare_exchange(current.data, new.data, success, failure)
143		{
144	0	Ok(data) => Ok(Epoch { data }),
145	0	Err(data) => Err(Epoch { data }),
146		}
147	0	} Unexecuted instantiation: <crossbeam_epoch::epoch::AtomicEpoch>::compare_exchange Unexecuted instantiation: <crossbeam_epoch::epoch::AtomicEpoch>::compare_exchange
148		}

Coverage Report

Created: 2026-08-13 08:17