Converts the pointer to a raw pointer (without the tag).

Examples

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

let o = Owned::new(1234);
let raw = &*o as *const _;
let a = Atomic::from(o);

let guard = &epoch::pin();
let p = a.load(SeqCst, guard);
assert_eq!(p.as_raw(), raw);
# unsafe { drop(a.into_owned()); } // avoid leak

Returns a new null pointer.

Examples

use crossbeam_epoch::Shared;

let p = Shared::<i32>::null();
assert!(p.is_null());

Returns true if the pointer is null.

Examples

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

let a = Atomic::null();
let guard = &epoch::pin();
assert!(a.load(SeqCst, guard).is_null());
a.store(Owned::new(1234), SeqCst);
assert!(!a.load(SeqCst, guard).is_null());
# unsafe { drop(a.into_owned()); } // avoid leak

Dereferences the pointer.

Returns a reference to the pointee that is valid during the lifetime 'g.

Safety

Dereferencing a pointer is unsafe because it could be pointing to invalid memory.

Another concern is the possibility of data races due to lack of proper synchronization. For example, consider the following scenario:

1. A thread creates a new object: a.store(Owned::new(10), Relaxed)
2. Another thread reads it: *a.load(Relaxed, guard).as_ref().unwrap()

The problem is that relaxed orderings don't synchronize initialization of the object with the read from the second thread. This is a data race. A possible solution would be to use Release and Acquire orderings.

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);
unsafe {
    assert_eq!(p.deref(), &1234);
}
# unsafe { drop(a.into_owned()); } // avoid leak

Dereferences the pointer.

Returns a mutable reference to the pointee that is valid during the lifetime 'g.

Safety

• There is no guarantee that there are no more threads attempting to read/write from/to the actual object at the same time.

  The user must know that there are no concurrent accesses towards the object itself.

• Other than the above, all safety concerns of deref() applies here.

Examples

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

let a = Atomic::new(vec![1, 2, 3, 4]);
let guard = &epoch::pin();

let mut p = a.load(SeqCst, guard);
unsafe {
    assert!(!p.is_null());
    let b = p.deref_mut();
    assert_eq!(b, &vec![1, 2, 3, 4]);
    b.push(5);
    assert_eq!(b, &vec![1, 2, 3, 4, 5]);
}

let p = a.load(SeqCst, guard);
unsafe {
    assert_eq!(p.deref(), &vec![1, 2, 3, 4, 5]);
}
# unsafe { drop(a.into_owned()); } // avoid leak

Converts the pointer to a reference.

Returns None if the pointer is null, or else a reference to the object wrapped in Some.

Safety

Dereferencing a pointer is unsafe because it could be pointing to invalid memory.

Another concern is the possibility of data races due to lack of proper synchronization. For example, consider the following scenario:

1. A thread creates a new object: a.store(Owned::new(10), Relaxed)
2. Another thread reads it: *a.load(Relaxed, guard).as_ref().unwrap()

The problem is that relaxed orderings don't synchronize initialization of the object with the read from the second thread. This is a data race. A possible solution would be to use Release and Acquire orderings.

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);
unsafe {
    assert_eq!(p.as_ref(), Some(&1234));
}
# unsafe { drop(a.into_owned()); } // avoid leak

Takes ownership of the pointee.

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

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

let a = Atomic::new(1234);
unsafe {
    let guard = &epoch::unprotected();
    let p = a.load(SeqCst, guard);
    drop(p.into_owned());
}

Takes ownership of the pointee if it is not null.

Safety

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

Examples

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

let a = Atomic::new(1234);
unsafe {
    let guard = &epoch::unprotected();
    let p = a.load(SeqCst, guard);
    if let Some(x) = p.try_into_owned() {
        drop(x);
    }
}

Returns the tag stored within the pointer.

Examples

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

let a = Atomic::<u64>::from(Owned::new(0u64).with_tag(2));
let guard = &epoch::pin();
let p = a.load(SeqCst, guard);
assert_eq!(p.tag(), 2);
# unsafe { drop(a.into_owned()); } // avoid leak

Returns the same pointer, but tagged with tag. tag is truncated to be fit into the unused bits of the pointer to T.

Examples

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

let a = Atomic::new(0u64);
let guard = &epoch::pin();
let p1 = a.load(SeqCst, guard);
let p2 = p1.with_tag(2);

assert_eq!(p1.tag(), 0);
assert_eq!(p2.tag(), 2);
assert_eq!(p1.as_raw(), p2.as_raw());
# unsafe { drop(a.into_owned()); } // avoid leak