Struct reclaim::Unlinked

#[must_use = "unlinked values are meant to be retired, otherwise a memory leak is highly likely"]
pub struct Unlinked<T, R, N> { /* fields omitted */ }

A reference to a value that has been removed from its previous location in memory and is hence no longer reachable by other threads.

Unlinked values are the result of (successful) atomic swap or compare-and-swap operations on Atomic values. They are move-only types, but they don't have full ownership semantics, either. Dropping an Unlinked value without explicitly retiring it almost certainly results in a memory leak.

The safety invariants around retiring Unlinked references are explained in detail in the documentation for retire_local.

Methods

impl<T, R: Reclaim, N: Unsigned> Unlinked<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(unlinked: 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(unlinked: &Self) -> (&T, usize)

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

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

Converts the Unlinked reference into an Unprotected.

pub unsafe fn cast<U>(unlinked: Self) -> Unlinked<U, R, N>

Casts the Unlinked to a reference to a different type.

Safety

The caller has to ensure the cast is valid.

pub unsafe fn retire_local(self, local: &R::Local) where
    T: 'static, 

Retires a record by calling retire_local on the generic reclamation parameter R.

Safety

The same caveats as with LocalReclaim::retire_local apply.

Note

This method takes self as receiver, which means it may conflict with methods of T, since Unlinked implements Deref. This is a deliberate trade-off in favor of better ergonomics around retiring records.

pub unsafe fn retire_local_unchecked(self, local: &R::Local)

Retires a record by calling retire_local_unchecked on the generic reclamation parameter R.

Safety

The same caveats as with LocalReclaim::retire_local_unchecked apply.

Note

This method takes self as receiver, which means it may conflict with methods of T, since Unlinked implements Deref. This is a deliberate trade-off in favor of better ergonomics around retiring records.

impl<T, R: GlobalReclaim, N: Unsigned> Unlinked<T, R, N>

pub unsafe fn retire(self) where
    T: 'static, 

Retires a record by calling retire on the generic reclamation parameter R.

Safety

The same caveats as with Reclaim::retire apply.

Note

This method takes self as receiver, which means it may conflict with methods of T, since Unlinked implements Deref. This is a deliberate trade-off in favor of better ergonomics around retiring records.

pub unsafe fn retire_unchecked(self)

Retires a record by calling retire_unchecked on the generic reclamation parameter R.

Safety

The same caveats as with Reclaim::retire_unchecked apply.

Note

This method takes self as receiver, which means it may conflict with methods of T, since Unlinked implements Deref. This is a deliberate trade-off in favor of better ergonomics around retiring records.

Trait Implementations

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

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

fn unmarked(unlinked: Self) -> Self

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

fn decompose(unlinked: 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 Unlinked<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: PartialEq, R: PartialEq, N: PartialEq> PartialEq<Unlinked<T, R, N>> for Unlinked<T, R, N>

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

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

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

This method tests for !=.

impl<T, R: Reclaim, N: Unsigned> AsRef<T> for Unlinked<T, R, N>

fn as_ref(&self) -> &T

Performs the conversion.

impl<T: PartialOrd, R: PartialOrd, N: PartialOrd> PartialOrd<Unlinked<T, R, N>> for Unlinked<T, R, N>

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

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

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

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

fn le(&self, other: &Unlinked<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: &Unlinked<T, R, N>) -> bool

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

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

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

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

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

fn cmp(&self, other: &Unlinked<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, R: Reclaim, N: Unsigned> Deref for Unlinked<T, R, N>

type Target = T

The resulting type after dereferencing.

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

Dereferences the value.

impl<T, R: Reclaim, N: Unsigned> Debug for Unlinked<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 Unlinked<T, R, N>

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

Formats the value using the given formatter.