Struct Shared

Source

pub struct Shared<T> { /* private fields */ }

Expand description

Shared is a reference-counted handle to an instance.

The instance is passed to the EBR garbage collector when the last strong reference is dropped.

Implementations§

Source §

impl<T: 'static> Shared<T>

Source

pub fn new(t: T) -> Self

Creates a new Shared.

The type of the instance must be determined at compile-time, must not contain non-static references, and must not be a non-static reference since the instance can, theoretically, survive the process. For instance, struct Disallowed<'l, T>(&'l T) is not allowed, because an instance of the type cannot outlive 'l whereas the garbage collector does not guarantee that the instance is dropped within 'l.

§Examples

use sdd::Shared;

let shared: Shared<usize> = Shared::new(31);

Source §

impl<T> Shared<T>

Source

pub unsafe fn new_unchecked(t: T) -> Self

Creates a new Shared without checking the lifetime of T.

§Safety

T::drop can be run after the last strong reference is dropped, therefore it is safe only if T::drop does not access short-lived data or std::mem::needs_drop is false for T. Otherwise, the instance must be manually dropped by invoking Self::drop_in_place before the lifetime of T is reached.

§Examples

use sdd::Shared;

let hello = String::from("hello");
let shared: Shared<&str> = unsafe { Shared::new_unchecked(hello.as_str()) };

assert!(unsafe { shared.drop_in_place() });

Source

pub fn get_guarded_ptr<'g>(&self, _guard: &'g Guard) -> Ptr<'g, T>

Returns a Ptr to the instance that may live as long as the supplied Guard.

§Examples

use sdd::{Guard, Shared};

let shared: Shared<usize> = Shared::new(37);
let guard = Guard::new();
let ptr = shared.get_guarded_ptr(&guard);
drop(shared);

assert_eq!(*ptr.as_ref().unwrap(), 37);

Source

pub fn get_guarded_ref<'g>(&self, _guard: &'g Guard) -> &'g T

Returns a reference to the instance that may live as long as the supplied Guard.

§Examples

use sdd::{Guard, Shared};

let shared: Shared<usize> = Shared::new(37);
let guard = Guard::new();
let ref_b = shared.get_guarded_ref(&guard);
drop(shared);

assert_eq!(*ref_b, 37);

Source

pub unsafe fn get_mut(&mut self) -> Option<&mut T>

Returns a mutable reference to the instance if the Shared is holding the only strong reference.

§Safety

The method is unsafe since there can be a Ptr to the instance without holding a strong reference.

§Examples

use sdd::Shared;

let mut shared: Shared<usize> = Shared::new(38);
unsafe {
    *shared.get_mut().unwrap() += 1;
}
assert_eq!(*shared, 39);

Source

pub fn as_ptr(&self) -> *const T

Provides a raw pointer to the instance.

§Examples

use sdd::Shared;
use std::sync::atomic::AtomicBool;
use std::sync::atomic::Ordering::Relaxed;

let shared: Shared<usize> = Shared::new(10);
let shared_clone: Shared<usize> = shared.clone();

assert_eq!(shared.as_ptr(), shared_clone.as_ptr());
assert_eq!(unsafe { *shared.as_ptr() }, unsafe { *shared_clone.as_ptr() });

Source

pub fn release(self) -> bool

Releases the strong reference by passing self to the given Guard.

Returns true if the last reference was released.

§Examples

use sdd::Shared;

let shared: Shared<usize> = Shared::new(47);
let shared_clone = shared.clone();
assert!(!shared.release());
assert!(shared_clone.release());

Source

pub unsafe fn drop_in_place(self) -> bool

Drops the instance immediately if it has held the last reference to the instance.

Returns true if the instance was dropped.

§Safety

The caller must ensure that there is no Ptr pointing to the instance.

§Examples

use sdd::Shared;
use std::sync::atomic::AtomicBool;
use std::sync::atomic::Ordering::Relaxed;

static DROPPED: AtomicBool = AtomicBool::new(false);
struct T(&'static AtomicBool);
impl Drop for T {
    fn drop(&mut self) {
        self.0.store(true, Relaxed);
    }
}

let shared: Shared<T> = Shared::new(T(&DROPPED));
let shared_clone = shared.clone();

unsafe {
    assert!(!shared.drop_in_place());
    assert!(!DROPPED.load(Relaxed));
    assert!(shared_clone.drop_in_place());
    assert!(DROPPED.load(Relaxed));
}