Struct reclaim::Owned

pub struct Owned<T, R: Reclaim, N: Unsigned> { /* fields omitted */ }

A pointer type for heap allocated values similar to Box.

Owned values function like marked pointers and are also guaranteed to allocate the appropriate RecordHeader type for its generic Reclaim parameter alongside their actual content.

Methods

impl<T, R: Reclaim, N: Unsigned> Owned<T, R, N>

pub fn new(owned: T) -> Self

Allocates memory for a Record<T> on the heap and then places a record with a default header and owned into it.

This does only allocate memory if at least one of RecordHeader or T are not zero-sized. If the RecordHeader is a ZST, this behaves identically to Box::new.

pub fn with_tag(owned: T, tag: usize) -> Self

Creates a new Owned like new but composes the returned pointer with an initial tag value.

Example

The primary use case for this is to pre-mark newly allocated values.

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

use reclaim::typenum::U1;
use reclaim::Shared;

type Atomic<T> = reclaim::leak::Atomic<T, U1>;
type Owned<T> = reclaim::leak::Owned<T, U1>;

let atomic = Atomic::null();
let owned = Owned::with_tag("string", 0b1);

atomic.store(owned, Ordering::Relaxed);
let shared = atomic.load_shared(Ordering::Relaxed);

assert_eq!((&"string", 0b1), Shared::decompose_ref(shared.unwrap()));

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(owned: 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(owned: &Self) -> (&T, usize)

Decomposes the internal marked pointer, returning a reference and the separated tag.

Example

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

use reclaim::typenum::U1;
use reclaim::leak::Owned;

type Atomic<T> = reclaim::leak::Atomic<T, U1>;

let mut atomic = Atomic::from(Owned::with_tag("string", 0b1));
// ... potential operations by other threads ...
let owned = atomic.take(); // after all threads have joined

assert_eq!((&"string", 0b1), Owned::decompose_ref(owned.as_ref().unwrap()));

pub fn decompose_mut(owned: &mut Self) -> (&mut T, usize)

Decomposes the internal marked pointer, returning a mutable reference and the separated tag.

pub fn leak<'a>(owned: Self) -> (&'a mut T, usize) where
    T: 'a, 

Consumes and leaks the Owned, returning a mutable reference &'a mut T and the decomposed tag. Note that the type T must outlive the chosen lifetime 'a. If the type has only static references, or none at all, then this may chosen to be 'static.

pub fn leak_unprotected(owned: Self) -> Unprotected<T, R, N>

Leaks the owned value and turns it into an Unprotected value, which has copy semantics, but can no longer be safely dereferenced.

Example

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

use reclaim::typenum::U0;
use reclaim::{Owned, Shared};

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

let atomic = Atomic::null();

let unprotected = Owned::leak_unprotected(Owned::new("string"));

loop {
    // `unprotected` is simply copied in every loop iteration
    if atomic.compare_exchange_weak(Shared::none(), unprotected, Relaxed, Relaxed).is_ok() {
        break;
    }
}

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

Leaks the owned value and turns it into a "protected" Shared value with arbitrary lifetime 'a.

Note, that the protection of the Shared value in this case stems from the fact, that the given owned could not have previously been part of a concurrent data structure (barring unsafe construction). This rules out concurrent reclamation by other threads.

Safety

Once a leaked Shared has been successfully inserted into a concurrent data structure, it must not be accessed any more, if there is the possibility for concurrent reclamation of the record.

Example

The use case for this method is similar to leak_unprotected but the leaked value can be safely dereferenced before being inserted into a shared data structure.

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

use reclaim::typenum::U0;
use reclaim::{Owned, Shared};

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

let atomic = Atomic::null();

let shared = unsafe {
    Owned::leak_shared(Owned::new("string"))
};

assert_eq!(&"string", &*shared);

loop {
    // `shared` is simply copied in every loop iteration
    if atomic.compare_exchange_weak(Shared::none(), shared, Relaxed, Relaxed).is_ok() {
        // if (non-leaking) reclamation is going on, `shared` must not be accessed
        // anymore after successful insertion!
        break;
    }
}

Trait Implementations

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

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

fn unmarked(owned: Self) -> Self

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

fn decompose(owned: 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: Reclaim, N: Unsigned> NonNullable for Owned<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<T, N>

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

impl<T, R: Reclaim, N: Unsigned> Drop for Owned<T, R, N>

fn drop(&mut self)

Executes the destructor for this type.

impl<T, R: Reclaim, N: Unsigned> From<Owned<T, R, N>> for Atomic<T, R, N>

fn from(owned: Owned<T, R, N>) -> Self

Performs the conversion.

impl<T, R: Reclaim, N: Unsigned> From<T> for Owned<T, R, N>

fn from(owned: T) -> Self

Performs the conversion.

impl<T: PartialEq, R: PartialEq + Reclaim, N: PartialEq + Unsigned> PartialEq<Owned<T, R, N>> for Owned<T, R, N>

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

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

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

This method tests for !=.

impl<T: Clone, R: Reclaim, N: Unsigned> Clone for Owned<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> AsMut<T> for Owned<T, R, N>

fn as_mut(&mut self) -> &mut T

Performs the conversion.

impl<T: Default, R: Reclaim, N: Unsigned> Default for Owned<T, R, N>

fn default() -> Self

Returns the "default value" for a type.

impl<T, R: Reclaim, N: Unsigned> Send for Owned<T, R, N> where
    T: Send, 

impl<T: PartialOrd, R: PartialOrd + Reclaim, N: PartialOrd + Unsigned> PartialOrd<Owned<T, R, N>> for Owned<T, R, N>

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

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

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

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

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

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

fn ge(&self, other: &Owned<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 + Reclaim, N: Eq + Unsigned> Eq for Owned<T, R, N>

impl<T: Ord, R: Ord + Reclaim, N: Ord + Unsigned> Ord for Owned<T, R, N>

fn cmp(&self, other: &Owned<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> Sync for Owned<T, R, N> where
    T: Sync, 

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

fn as_ref(&self) -> &T

Performs the conversion.

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

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

Formats the value using the given formatter.

impl<T, R: Reclaim, N: Unsigned> DerefMut for Owned<T, R, N>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

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

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

Formats the value using the given formatter.

impl<T, R: Reclaim, N: Unsigned> BorrowMut<T> for Owned<T, R, N>

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value.

impl<T, R: Reclaim, N: Unsigned> Borrow<T> for Owned<T, R, N>

fn borrow(&self) -> &T

Immutably borrows from an owned value.