Struct reclaim::Shared

pub struct Shared<'g, T, R, N> { /* fields omitted */ }

A shared reference to a value that is actively protected from reclamation by other threads.

Shared values have similar semantics to shared references (&'g T), i.e. they can be trivially copied, cloned and (safely) de-referenced. However, they do retain potential mark bits of the atomic value from which they were originally read. They are also usually borrowed from guard values implementing the Protect trait.

Methods

impl<'g, T, R: Reclaim, N: Unsigned> Shared<'g, T, R, N>

pub fn none() -> Option<Self>

Creates a None variant for an Option<Self>.

This is useful for calls to store, swap or compare_exchange_*, when a null pointer needs to be inserted. These methods accept values of various non-nullable pointer types (Shared, Owned, Unlinked and Unprotected) and Option types thereof as argument. However, the compiler is usually not able to infer the concrete type, when a None is inserted, and this function is intended for these cases.

Example

use std::sync::atomic::Ordering;

type Atomic<T> = reclaim::leak::Atomic<T, reclaim::typenum::U0>;
type Owned<T> = reclaim::leak::Owned<T, reclaim::typenum::U0>;
type Unlinked<T> = reclaim::leak::Unlinked<T, reclaim::typenum::U0>;

let atomic = Atomic::new(1);
let swap = atomic.swap(Owned::none(), Ordering::Relaxed).unwrap();

assert_eq!(swap.as_ref(), &1);
unsafe { Unlinked::retire(swap) }; // leaks memory

pub fn null() -> Marked<Self>

Creates an unmarked Null variant for a Marked<Self>.

pub fn null_with_tag(tag: usize) -> Marked<Self>

Creates a marked Null variant for a Marked<Self> with the given tag.

pub fn compose(shared: Self, tag: usize) -> Self

Consumes the given Self and returns the same value but with the specified tag.

Any previous tag is overwritten.

pub fn decompose_ref(shared: Self) -> (&'g T, usize)

Decomposes the marked reference, returning the reference itself and the separated tag.

pub fn into_ref(shared: Self) -> &'g T

Consumes and decomposes the marked reference, returning only the reference itself.

Example

Derefencing a Shared through the Deref implementation ties the returned reference to the shorter lifetime of the shared itself. Use this function to get a reference with the full lifetime 'g.

use core::sync::atomic::Ordering::Relaxed;

use reclaim::prelude::*;
use reclaim::typenum::U0;
use reclaim::leak::Shared;

type Atomic<T> = reclaim::leak::Atomic<T, U0>;
type Guard = reclaim::leak::Guard;

let atomic = Atomic::new("string");

let mut guard = Guard::new();
let shared = atomic.load(Relaxed, &mut guard);

let reference = Shared::into_ref(shared.unwrap());
assert_eq!(reference, &"string");

pub fn into_unprotected(shared: Self) -> Unprotected<T, R, N>

Converts the Shared reference into an Unprotected.

pub unsafe fn cast<'h, U>(shared: Self) -> Shared<'h, U, R, N>

Casts the Shared to a reference to a different type and with a different lifetime.

This can be useful to extend the lifetime of a Shared in cases the borrow checker is unable to correctly determine the relationship between mutable borrows of guards and the resulting shared references.

Safety

The caller has to ensure the cast is valid both in terms of type and lifetime.

Trait Implementations

impl<'g, T, R: Reclaim, N: Unsigned> MarkedPointer for Shared<'g, T, R, N>

type Pointer = Self

The pointer type.

type Item = T

The pointed-to type.

type MarkBits = N

Number of bits available for tagging.

fn as_marked_ptr(&self) -> MarkedPtr<T, N>

Returns the equivalent raw marked pointer.

fn into_marked_ptr(self) -> MarkedPtr<Self::Item, Self::MarkBits>

Consumes self and returns the equivalent raw marked pointer.

fn marked(shared: Self, tag: usize) -> Marked<Self::Pointer>

Consumes the Self and returns the same value with the specified tag wrapped in a Marked.

fn unmarked(shared: Self) -> Self

Consumes the Self and returns the same value but without any tag.

fn decompose(shared: Self) -> (Self, usize)

Decomposes the Self, returning the original value without its previous tag and the separated tag.

unsafe fn from_marked_ptr(marked: MarkedPtr<Self::Item, Self::MarkBits>) -> Self

Constructs a Self from a raw marked pointer.

unsafe fn from_marked_non_null(
    marked: MarkedNonNull<Self::Item, Self::MarkBits>
) -> Self

Constructs a Self from a raw non-null marked pointer

impl<'g, T, R, N: Unsigned> NonNullable for Shared<'g, T, R, N>

type Item = T

The pointed-to type.

type MarkBits = N

Number of bits available for tagging.

fn into_marked_non_null(self) -> MarkedNonNull<Self::Item, Self::MarkBits>

Converts the given Self into a equivalent marked non-null pointer.

impl<'g, T, R, N> Copy for Shared<'g, T, R, N>

impl<'g, T, R: Reclaim, N: Unsigned> AsRef<T> for Shared<'g, T, R, N>

fn as_ref(&self) -> &T

Performs the conversion.

impl<'g, T, R, N> Clone for Shared<'g, T, N, R>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'g, T, R: Reclaim, N: Unsigned> Deref for Shared<'g, T, R, N>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'g, T, R: Reclaim, N: Unsigned> Debug for Shared<'g, T, R, N>

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

Formats the value using the given formatter.

impl<'g, T, R: Reclaim, N: Unsigned> Pointer for Shared<'g, T, R, N>

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

Formats the value using the given formatter.