impl<'g, T> Shared<'g, T>

fn as_raw(self: &Self) -> *const T

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

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

fn null() -> Shared<'g, T>

Returns a new null pointer.

Examples

use crossbeam_epoch::Shared;

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

fn is_null(self: &Self) -> bool

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

unsafe fn deref(self: &Self) -> &'g T

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

unsafe fn deref_mut(self: &mut Self) -> &'g mut T

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

unsafe fn as_ref(self: &Self) -> Option<&'g T>

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

unsafe fn into_owned(self: Self) -> Owned<T>

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

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

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

fn tag(self: &Self) -> usize

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

fn with_tag(self: &Self, tag: usize) -> Shared<'g, T>

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

impl<'g, T> Freeze for Shared<'g, T>

impl<'g, T> RefUnwindSafe for Shared<'g, T>

impl<'g, T> Send for Shared<'g, T>

impl<'g, T> Sync for Shared<'g, T>

impl<'g, T> Unpin for Shared<'g, T>

impl<'g, T> UnsafeUnpin for Shared<'g, T>

impl<'g, T> UnwindSafe for Shared<'g, T>

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

fn eq(self: &Self, other: &Self) -> bool

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

fn partial_cmp(self: &Self, other: &Self) -> Option<Ordering>

impl<T> Any for Shared<'g, T>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Shared<'g, T>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for Shared<'g, T>

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

impl<T> CloneToUninit for Shared<'g, T>

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for Shared<'_, T>

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

Returns a new pointer pointing to raw.

Panics

Panics if raw is not properly aligned.

Examples

use crossbeam_epoch::Shared;

let p = Shared::from(Box::into_raw(Box::new(1234)) as *const _);
assert!(!p.is_null());
# unsafe { drop(p.into_owned()); } // avoid leak

impl<T> From for Shared<'g, T>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> Pointable for Shared<'g, T>

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

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

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

unsafe fn drop(ptr: usize)

impl<T> ToOwned for Shared<'g, T>

fn to_owned(self: &Self) -> T

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

impl<T, U> Into for Shared<'g, T>

fn into(self: Self) -> U

Calls U::from(self).

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

impl<T, U> TryFrom for Shared<'g, T>

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

impl<T, U> TryInto for Shared<'g, T>

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

impl<T: ?Sized + Pointable> Clone for Shared<'_, T>

fn clone(self: &Self) -> Self

impl<T: ?Sized + Pointable> Copy for Shared<'_, T>

impl<T: ?Sized + Pointable> Debug for Shared<'_, T>

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

impl<T: ?Sized + Pointable> Default for Shared<'_, T>

fn default() -> Self

impl<T: ?Sized + Pointable> Eq for Shared<'_, T>

impl<T: ?Sized + Pointable> Ord for Shared<'_, T>

fn cmp(self: &Self, other: &Self) -> Ordering

impl<T: ?Sized + Pointable> Pointer for Shared<'_, T>

fn into_usize(self: Self) -> usize

unsafe fn from_usize(data: usize) -> Self

impl<T: ?Sized + Pointable> Pointer for Shared<'_, T>

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