Struct crossbeam_epoch::Shared

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

A pointer to an object protected by the epoch GC.

The pointer is valid for use only during the lifetime 'g.

The pointer must be properly aligned. Since it is aligned, a tag can be stored into the unused least significant bits of the address.

Implementations§

source§

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

source

pub fn as_raw(&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);
source§

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

source

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

Returns a new null pointer.

Examples
use crossbeam_epoch::Shared;

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

pub fn is_null(&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());
source

pub unsafe fn deref(&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);
}
source

pub unsafe fn deref_mut(&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]);
}
source

pub unsafe fn as_ref(&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));
}
source

pub unsafe fn into_owned(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());
}
source

pub unsafe fn try_into_owned(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);
    }
}
source

pub fn tag(&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);
source

pub fn with_tag(&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());

Trait Implementations§

source§

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

source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
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 Shared<'_, 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 Shared<'_, T>

source§

fn default() -> Self

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

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

source§

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());
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: ?Sized + Pointable> Ord for Shared<'_, T>

source§

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

This method returns an Ordering between self and other. Read more
1.21.0 · source§

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values. Read more
1.21.0 · source§

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values. Read more
1.50.0 · source§

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval. Read more
source§

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

source§

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

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

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

source§

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

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more
source§

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

source§

fn into_usize(self) -> usize

Returns the machine representation of the pointer.
source§

unsafe fn from_usize(data: usize) -> Self

Returns a new pointer pointing to the tagged pointer data. Read more
source§

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

source§

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

Formats the value using the given formatter.
source§

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

source§

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

Auto Trait Implementations§

§

impl<'g, T: ?Sized> RefUnwindSafe for Shared<'g, T>where T: RefUnwindSafe,

§

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

§

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

§

impl<'g, T: ?Sized> Unpin for Shared<'g, T>

§

impl<'g, T: ?Sized> UnwindSafe for Shared<'g, 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<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.