Struct reclaim::Unprotected

pub struct Unprotected<T, R, N> { /* fields omitted */ }

A reference to a value loaded from an Atomic that is not actively protected from reclamation.

Unprotected values can not be safely de-referenced under usual circumstances (i.e. other threads can retire and reclaim unlinked records). They do, however, have stronger guarantees than raw (marked) pointers: Since are loaded from Atomic values they must (at least at one point) have been valid references.

Methods

impl<T, R: Reclaim, N: Unsigned> Unprotected<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(unprotected: Self, tag: usize) -> Self

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

Any previous tag is overwritten.

pub unsafe fn deref_unprotected<'a>(self) -> &'a T

Dereferences the Unprotected, returning the resulting reference which is not bound to the lifetime of self.

Safety

Since the pointed-to value is not protected from reclamation it could be freed at any point (even before calling this method). Hence, this method is only safe to call if the caller can guarantee that no reclamation can occur, e.g. when records are never retired at all.

Example

...

pub unsafe fn decompose_ref_unprotected<'a>(self) -> (&'a T, usize)

Decomposes the Unprotected, returning the reference (which is not bound to the lifetime of self) itself and the separated tag.

Safety

Since the pointed-to value is not protected from reclamation it could be freed at any point (even before calling this method). Hence, this method is only safe to call if the caller can guarantee that no reclamation can occur, e.g. when records are never retired at all.

pub unsafe fn into_shared<'a>(unprotected: Self) -> Shared<'a, T, R, N>

Consumes the unprotected and converts it to a Shared reference with arbitrary lifetime.

Safety

The returned reference is not in fact protected and could be reclaimed by other threads, so the caller has to ensure no concurrent reclamation is possible.

pub fn cast<U>(unprotected: Self) -> Unprotected<U, R, N>

Casts the Unprotected to a reference to a different type.

Trait Implementations

impl<T, R: Reclaim, N: Unsigned> MarkedPointer for Unprotected<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(unprotected: Self, tag: usize) -> Marked<Self::Pointer>

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

fn unmarked(unprotected: Self) -> Self

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

fn decompose(unprotected: 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<T, R, N: Unsigned> NonNullable for Unprotected<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<T: PartialOrd, R: PartialOrd, N: PartialOrd> PartialOrd<Unprotected<T, R, N>> for Unprotected<T, R, N>

fn partial_cmp(&self, other: &Unprotected<T, R, N>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Unprotected<T, R, N>) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Unprotected<T, R, N>) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Unprotected<T, R, N>) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Unprotected<T, R, N>) -> bool

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

impl<T: PartialEq, R: PartialEq, N: PartialEq> PartialEq<Unprotected<T, R, N>> for Unprotected<T, R, N>

fn eq(&self, other: &Unprotected<T, R, N>) -> bool

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

fn ne(&self, other: &Unprotected<T, R, N>) -> bool

This method tests for !=.

impl<T, R: Reclaim, N> Copy for Unprotected<T, R, N>

impl<T: Ord, R: Ord, N: Ord> Ord for Unprotected<T, R, N>

fn cmp(&self, other: &Unprotected<T, R, N>) -> Ordering

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<T: Eq, R: Eq, N: Eq> Eq for Unprotected<T, R, N>

impl<T, R, N> Clone for Unprotected<T, R, N>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T, R: Reclaim, N: Unsigned> Debug for Unprotected<T, R, N>

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

Formats the value using the given formatter.

impl<T, R: Reclaim, N: Unsigned> Pointer for Unprotected<T, R, N>

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

Formats the value using the given formatter.