Struct crossbeam_epoch::Atomic

source · 
pub struct Atomic<T> { /* 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. More precisely, a tag 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.

Implementations

Returns a new null atomic pointer.

Examples
use crossbeam_epoch::Atomic;

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

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

Examples
use crossbeam_epoch::Atomic;

let a = Atomic::new(1234);

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);

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);

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::{self as 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);

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, Owned, Shared};
use std::sync::atomic::Ordering::SeqCst;

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

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.

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 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);

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.

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,
    }
}

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);

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);

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);

Trait Implementations

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.

Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more
Returns the “default value” for a type. Read more

Returns a new atomic pointer pointing to raw.

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

let a = Atomic::<i32>::from(ptr::null::<i32>());
Converts to this type from the input type.

Returns a new atomic pointer pointing to owned.

Examples
use crossbeam_epoch::{Atomic, Owned};

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

Returns a new atomic pointer pointing to ptr.

Examples
use crossbeam_epoch::{Atomic, Shared};

let a = Atomic::<i32>::from(Shared::<i32>::null());
Converts to this type from the input type.
Formats the value using the given formatter.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
Converts to this type from the input type.

Returns the argument unchanged.

Calls U::from(self).

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

The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.