Struct crossbeam_epoch::Atomic

source ·
pub struct Atomic<T: ?Sized + Pointable> { /* private fields */ }
Expand description

An atomic pointer that can be safely shared between threads.

The pointer must be properly aligned. Since it is aligned, a tag can be stored into the unused least significant bits of the address. For example, the tag for a pointer to a sized type T should be less than (1 << mem::align_of::<T>().trailing_zeros()).

Any method that loads the pointer must be passed a reference to a Guard.

Crossbeam supports dynamically sized types. See Pointable for details.

Implementations§

source§

impl<T> Atomic<T>

source

pub fn new(init: T) -> Atomic<T>

Allocates value on the heap and returns a new atomic pointer pointing to it.

Examples
use crossbeam_epoch::Atomic;

let a = Atomic::new(1234);
source§

impl<T: ?Sized + Pointable> Atomic<T>

source

pub fn init(init: T::Init) -> Atomic<T>

Allocates value on the heap and returns a new atomic pointer pointing to it.

Examples
use crossbeam_epoch::Atomic;

let a = Atomic::<i32>::init(1234);
source

pub const fn null() -> Atomic<T>

Returns a new null atomic pointer.

Examples
use crossbeam_epoch::Atomic;

let a = Atomic::<i32>::null();
source

pub fn load<'g>(&self, ord: Ordering, _: &'g Guard) -> Shared<'g, T>

Loads a Shared from the atomic pointer.

This method takes an Ordering argument which describes the memory ordering of this operation.

Examples
use crossbeam_epoch::{self as epoch, Atomic};
use std::sync::atomic::Ordering::SeqCst;

let a = Atomic::new(1234);
let guard = &epoch::pin();
let p = a.load(SeqCst, guard);
source

pub fn load_consume<'g>(&self, _: &'g Guard) -> Shared<'g, T>

Loads a Shared from the atomic pointer using a “consume” memory ordering.

This is similar to the “acquire” ordering, except that an ordering is only guaranteed with operations that “depend on” the result of the load. However consume loads are usually much faster than acquire loads on architectures with a weak memory model since they don’t require memory fence instructions.

The exact definition of “depend on” is a bit vague, but it works as you would expect in practice since a lot of software, especially the Linux kernel, rely on this behavior.

Examples
use crossbeam_epoch::{self as epoch, Atomic};

let a = Atomic::new(1234);
let guard = &epoch::pin();
let p = a.load_consume(guard);
source

pub fn store<P: Pointer<T>>(&self, new: P, ord: Ordering)

Stores a Shared or Owned pointer into the atomic pointer.

This method takes an Ordering argument which describes the memory ordering of this operation.

Examples
use crossbeam_epoch::{Atomic, Owned, Shared};
use std::sync::atomic::Ordering::SeqCst;

let a = Atomic::new(1234);
a.store(Shared::null(), SeqCst);
a.store(Owned::new(1234), SeqCst);
source

pub fn swap<'g, P: Pointer<T>>( &self, new: P, ord: Ordering, _: &'g Guard ) -> Shared<'g, T>

Stores a Shared or Owned pointer into the atomic pointer, returning the previous Shared.

This method takes an Ordering argument which describes the memory ordering of this operation.

Examples
use crossbeam_epoch::{self as epoch, Atomic, Shared};
use std::sync::atomic::Ordering::SeqCst;

let a = Atomic::new(1234);
let guard = &epoch::pin();
let p = a.swap(Shared::null(), SeqCst, guard);
source

pub fn compare_exchange<'g, P>( &self, current: Shared<'_, T>, new: P, success: Ordering, failure: Ordering, _: &'g Guard ) -> Result<Shared<'g, T>, CompareExchangeError<'g, T, P>>where P: Pointer<T>,

Stores the pointer new (either Shared or Owned) into the atomic pointer if the current value is the same as current. The tag is also taken into account, so two pointers to the same object, but with different tags, will not be considered equal.

The return value is a result indicating whether the new pointer was written. On success the pointer that was written is returned. On failure the actual current value and new are returned.

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.

Examples
use crossbeam_epoch::{self as epoch, Atomic, Owned, Shared};
use std::sync::atomic::Ordering::SeqCst;

let a = Atomic::new(1234);

let guard = &epoch::pin();
let curr = a.load(SeqCst, guard);
let res1 = a.compare_exchange(curr, Shared::null(), SeqCst, SeqCst, guard);
let res2 = a.compare_exchange(curr, Owned::new(5678), SeqCst, SeqCst, guard);
source

pub fn compare_exchange_weak<'g, P>( &self, current: Shared<'_, T>, new: P, success: Ordering, failure: Ordering, _: &'g Guard ) -> Result<Shared<'g, T>, CompareExchangeError<'g, T, P>>where P: Pointer<T>,

Stores the pointer new (either Shared or Owned) into the atomic pointer if the current value is the same as current. The tag is also taken into account, so two pointers to the same object, but with different tags, will not be considered equal.

Unlike compare_exchange, this method is allowed to spuriously fail even when comparison succeeds, which can result in more efficient code on some platforms. The return value is a result indicating whether the new pointer was written. On success the pointer that was written is returned. On failure the actual current value and new are returned.

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.

Examples
use crossbeam_epoch::{self as epoch, Atomic, Owned, Shared};
use std::sync::atomic::Ordering::SeqCst;

let a = Atomic::new(1234);
let guard = &epoch::pin();

let mut new = Owned::new(5678);
let mut ptr = a.load(SeqCst, guard);
loop {
    match a.compare_exchange_weak(ptr, new, SeqCst, SeqCst, guard) {
        Ok(p) => {
            ptr = p;
            break;
        }
        Err(err) => {
            ptr = err.current;
            new = err.new;
        }
    }
}

let mut curr = a.load(SeqCst, guard);
loop {
    match a.compare_exchange_weak(curr, Shared::null(), SeqCst, SeqCst, guard) {
        Ok(_) => break,
        Err(err) => curr = err.current,
    }
}
source

pub fn fetch_update<'g, F>( &self, set_order: Ordering, fail_order: Ordering, guard: &'g Guard, func: F ) -> Result<Shared<'g, T>, Shared<'g, T>>where F: FnMut(Shared<'g, T>) -> Option<Shared<'g, T>>,

Fetches the pointer, and then applies a function to it that returns a new value. Returns a Result of Ok(previous_value) if the function returned Some, else Err(_).

Note that the given function may be called multiple times if the value has been changed by other threads in the meantime, as long as the function returns Some(_), but the function will have been applied only once to the stored value.

fetch_update takes two Ordering arguments to describe the memory ordering of this operation. The first describes the required ordering for when the operation finally succeeds while the second describes the required ordering for loads. These correspond to the success and failure orderings of Atomic::compare_exchange respectively.

Using Acquire as success ordering makes the store part of this operation Relaxed, and using Release makes the final successful load Relaxed. The (failed) load ordering can only be SeqCst, Acquire or Relaxed and must be equivalent to or weaker than the success ordering.

Examples
use crossbeam_epoch::{self as epoch, Atomic};
use std::sync::atomic::Ordering::SeqCst;

let a = Atomic::new(1234);
let guard = &epoch::pin();

let res1 = a.fetch_update(SeqCst, SeqCst, guard, |x| Some(x.with_tag(1)));
assert!(res1.is_ok());

let res2 = a.fetch_update(SeqCst, SeqCst, guard, |x| None);
assert!(res2.is_err());
source

pub fn compare_and_set<'g, O, P>( &self, current: Shared<'_, T>, new: P, ord: O, guard: &'g Guard ) -> Result<Shared<'g, T>, CompareAndSetError<'g, T, P>>where O: CompareAndSetOrdering, P: Pointer<T>,

👎Deprecated: Use compare_exchange instead

Stores the pointer new (either Shared or Owned) into the atomic pointer if the current value is the same as current. The tag is also taken into account, so two pointers to the same object, but with different tags, will not be considered equal.

The return value is a result indicating whether the new pointer was written. On success the pointer that was written is returned. On failure the actual current value and new are returned.

This method takes a CompareAndSetOrdering argument which describes the memory ordering of this operation.

Migrating to compare_exchange

compare_and_set is equivalent to compare_exchange with the following mapping for memory orderings:

OriginalSuccessFailure
RelaxedRelaxedRelaxed
AcquireAcquireAcquire
ReleaseReleaseRelaxed
AcqRelAcqRelAcquire
SeqCstSeqCstSeqCst
Examples
use crossbeam_epoch::{self as epoch, Atomic, Owned, Shared};
use std::sync::atomic::Ordering::SeqCst;

let a = Atomic::new(1234);

let guard = &epoch::pin();
let curr = a.load(SeqCst, guard);
let res1 = a.compare_and_set(curr, Shared::null(), SeqCst, guard);
let res2 = a.compare_and_set(curr, Owned::new(5678), SeqCst, guard);
source

pub fn compare_and_set_weak<'g, O, P>( &self, current: Shared<'_, T>, new: P, ord: O, guard: &'g Guard ) -> Result<Shared<'g, T>, CompareAndSetError<'g, T, P>>where O: CompareAndSetOrdering, P: Pointer<T>,

👎Deprecated: Use compare_exchange_weak instead

Stores the pointer new (either Shared or Owned) into the atomic pointer if the current value is the same as current. The tag is also taken into account, so two pointers to the same object, but with different tags, will not be considered equal.

Unlike compare_and_set, this method is allowed to spuriously fail even when comparison succeeds, which can result in more efficient code on some platforms. The return value is a result indicating whether the new pointer was written. On success the pointer that was written is returned. On failure the actual current value and new are returned.

This method takes a CompareAndSetOrdering argument which describes the memory ordering of this operation.

Migrating to compare_exchange_weak

compare_and_set_weak is equivalent to compare_exchange_weak with the following mapping for memory orderings:

OriginalSuccessFailure
RelaxedRelaxedRelaxed
AcquireAcquireAcquire
ReleaseReleaseRelaxed
AcqRelAcqRelAcquire
SeqCstSeqCstSeqCst
Examples
use crossbeam_epoch::{self as epoch, Atomic, Owned, Shared};
use std::sync::atomic::Ordering::SeqCst;

let a = Atomic::new(1234);
let guard = &epoch::pin();

let mut new = Owned::new(5678);
let mut ptr = a.load(SeqCst, guard);
loop {
    match a.compare_and_set_weak(ptr, new, SeqCst, guard) {
        Ok(p) => {
            ptr = p;
            break;
        }
        Err(err) => {
            ptr = err.current;
            new = err.new;
        }
    }
}

let mut curr = a.load(SeqCst, guard);
loop {
    match a.compare_and_set_weak(curr, Shared::null(), SeqCst, guard) {
        Ok(_) => break,
        Err(err) => curr = err.current,
    }
}
source

pub fn fetch_and<'g>( &self, val: usize, ord: Ordering, _: &'g Guard ) -> Shared<'g, T>

Bitwise “and” with the current tag.

Performs a bitwise “and” operation on the current tag and the argument val, and sets the new tag to the result. Returns the previous pointer.

This method takes an Ordering argument which describes the memory ordering of this operation.

Examples
use crossbeam_epoch::{self as epoch, Atomic, Shared};
use std::sync::atomic::Ordering::SeqCst;

let a = Atomic::<i32>::from(Shared::null().with_tag(3));
let guard = &epoch::pin();
assert_eq!(a.fetch_and(2, SeqCst, guard).tag(), 3);
assert_eq!(a.load(SeqCst, guard).tag(), 2);
source

pub fn fetch_or<'g>( &self, val: usize, ord: Ordering, _: &'g Guard ) -> Shared<'g, T>

Bitwise “or” with the current tag.

Performs a bitwise “or” operation on the current tag and the argument val, and sets the new tag to the result. Returns the previous pointer.

This method takes an Ordering argument which describes the memory ordering of this operation.

Examples
use crossbeam_epoch::{self as epoch, Atomic, Shared};
use std::sync::atomic::Ordering::SeqCst;

let a = Atomic::<i32>::from(Shared::null().with_tag(1));
let guard = &epoch::pin();
assert_eq!(a.fetch_or(2, SeqCst, guard).tag(), 1);
assert_eq!(a.load(SeqCst, guard).tag(), 3);
source

pub fn fetch_xor<'g>( &self, val: usize, ord: Ordering, _: &'g Guard ) -> Shared<'g, T>

Bitwise “xor” with the current tag.

Performs a bitwise “xor” operation on the current tag and the argument val, and sets the new tag to the result. Returns the previous pointer.

This method takes an Ordering argument which describes the memory ordering of this operation.

Examples
use crossbeam_epoch::{self as epoch, Atomic, Shared};
use std::sync::atomic::Ordering::SeqCst;

let a = Atomic::<i32>::from(Shared::null().with_tag(1));
let guard = &epoch::pin();
assert_eq!(a.fetch_xor(3, SeqCst, guard).tag(), 1);
assert_eq!(a.load(SeqCst, guard).tag(), 2);
source

pub unsafe fn into_owned(self) -> Owned<T>

Takes ownership of the pointee.

This consumes the atomic and converts it into Owned. As Atomic doesn’t have a destructor and doesn’t drop the pointee while Owned does, this is suitable for destructors of data structures.

Panics

Panics if this pointer is null, but only in debug mode.

Safety

This method may be called only if the pointer is valid and nobody else is holding a reference to the same object.

Examples
struct DataStructure {
    ptr: Atomic<usize>,
}

impl Drop for DataStructure {
    fn drop(&mut self) {
        // By now the DataStructure lives only in our thread and we are sure we don't hold
        // any Shared or & to it ourselves.
        unsafe {
            drop(mem::replace(&mut self.ptr, Atomic::null()).into_owned());
        }
    }
}
source

pub unsafe fn try_into_owned(self) -> Option<Owned<T>>

Takes ownership of the pointee if it is non-null.

This consumes the atomic and converts it into Owned. As Atomic doesn’t have a destructor and doesn’t drop the pointee while Owned does, this is suitable for destructors of data structures.

Safety

This method may be called only if the pointer is valid and nobody else is holding a reference to the same object, or the pointer is null.

Examples
struct DataStructure {
    ptr: Atomic<usize>,
}

impl Drop for DataStructure {
    fn drop(&mut self) {
        // By now the DataStructure lives only in our thread and we are sure we don't hold
        // any Shared or & to it ourselves, but it may be null, so we have to be careful.
        let old = mem::replace(&mut self.ptr, Atomic::null());
        unsafe {
            if let Some(x) = old.try_into_owned() {
                drop(x)
            }
        }
    }
}

Trait Implementations§

source§

impl<T: ?Sized + Pointable> Clone for Atomic<T>

source§

fn clone(&self) -> Self

Returns a copy of the atomic value.

Note that a Relaxed load is used here. If you need synchronization, use it with other atomics or fences.

1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl<T: ?Sized + Pointable> Debug for Atomic<T>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl<T: ?Sized + Pointable> Default for Atomic<T>

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

impl<T> From<*const T> for Atomic<T>

source§

fn from(raw: *const T) -> Self

Returns a new atomic pointer pointing to raw.

Examples
use std::ptr;
use crossbeam_epoch::Atomic;

let a = Atomic::<i32>::from(ptr::null::<i32>());
source§

impl<T> From<Box<T, Global>> for Atomic<T>

source§

fn from(b: Box<T>) -> Self

Converts to this type from the input type.
source§

impl<T: ?Sized + Pointable> From<Owned<T>> for Atomic<T>

source§

fn from(owned: Owned<T>) -> Self

Returns a new atomic pointer pointing to owned.

Examples
use crossbeam_epoch::{Atomic, Owned};

let a = Atomic::<i32>::from(Owned::new(1234));
source§

impl<'g, T: ?Sized + Pointable> From<Shared<'g, T>> for Atomic<T>

source§

fn from(ptr: Shared<'g, T>) -> Self

Returns a new atomic pointer pointing to ptr.

Examples
use crossbeam_epoch::{Atomic, Shared};

let a = Atomic::<i32>::from(Shared::<i32>::null());
source§

impl<T> From<T> for Atomic<T>

source§

fn from(t: T) -> Self

Converts to this type from the input type.
source§

impl<T: ?Sized + Pointable> Pointer for Atomic<T>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.
source§

impl<T: ?Sized + Pointable + Send + Sync> Send for Atomic<T>

source§

impl<T: ?Sized + Pointable + Send + Sync> Sync for Atomic<T>

Auto Trait Implementations§

§

impl<T: ?Sized> RefUnwindSafe for Atomic<T>where T: RefUnwindSafe,

§

impl<T: ?Sized> Unpin for Atomic<T>

§

impl<T: ?Sized> UnwindSafe for Atomic<T>where T: RefUnwindSafe,

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<!> for T

source§

fn from(t: !) -> T

Converts to this type from the input type.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Pointable for T

source§

const ALIGN: usize = const ALIGN: usize = mem::align_of::<T>();

The alignment of pointer.
§

type Init = T

The type for initializers.
source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.