Struct crossbeam_epoch::Shared
source · [−]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
sourceimpl<'g, T> Shared<'g, T>
impl<'g, T> Shared<'g, T>
sourcepub fn as_raw(&self) -> *const T
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);
sourceimpl<'g, T: ?Sized + Pointable> Shared<'g, T>
impl<'g, T: ?Sized + Pointable> Shared<'g, T>
sourcepub fn null() -> Shared<'g, T>
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());
sourcepub fn is_null(&self) -> bool
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());
sourcepub unsafe fn deref(&self) -> &'g T
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:
- A thread creates a new object:
a.store(Owned::new(10), Relaxed)
- 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);
}
sourcepub unsafe fn deref_mut(&mut self) -> &'g mut T
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]);
}
sourcepub unsafe fn as_ref(&self) -> Option<&'g T>
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:
- A thread creates a new object:
a.store(Owned::new(10), Relaxed)
- 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));
}
sourcepub unsafe fn into_owned(self) -> Owned<T>
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());
}
sourcepub fn tag(&self) -> usize
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);
sourcepub fn with_tag(&self, tag: usize) -> Shared<'g, T>
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
sourceimpl<T: ?Sized + Pointable> Ord for Shared<'_, T>
impl<T: ?Sized + Pointable> Ord for Shared<'_, T>
sourcefn partial_cmp(&self, other: &Self) -> Option<Ordering>
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 · sourcefn lt(&self, other: &Rhs) -> bool
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 · sourcefn le(&self, other: &Rhs) -> bool
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
sourceimpl<T: ?Sized + Pointable> Pointer<T> for Shared<'_, T>
impl<T: ?Sized + Pointable> Pointer<T> for Shared<'_, T>
sourcefn into_usize(self) -> usize
fn into_usize(self) -> usize
Returns the machine representation of the pointer.
sourceunsafe fn from_usize(data: usize) -> Self
unsafe fn from_usize(data: usize) -> Self
Returns a new pointer pointing to the tagged pointer data
. Read more
impl<T: ?Sized + Pointable> Copy for Shared<'_, T>
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
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcepub fn borrow_mut(&mut self) -> &mut T
pub fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcepub fn to_owned(&self) -> T
pub fn to_owned(&self) -> T
Creates owned data from borrowed data, usually by cloning. Read more
sourcepub fn clone_into(&self, target: &mut T)
pub fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more