Struct RecycleBox

Source

pub struct RecycleBox<T>where
    T: ?Sized,
{ /* private fields */ }

Expand description

A pointer type for heap-allocated objects which heap storage can be re-used.

See the module-level documentation for more.

Implementations§

Source §

impl<T> RecycleBox<T>

Source

pub fn new(x: T) -> Self

Allocates heap memory based on the size of T and places x into it.

Source

pub fn with_layout(x: T, layout: Layout) -> Self

Allocates heap memory based on the specified layout and places x into it.

If type T does not fit within the specified layout, the layout alignment and size are increased as needed.

Source

pub fn replace(boxed: Self, x: U) -> (T, RecycleBox)

Consumes the box and return both the old value and a new box, re-using if possible the already allocated memory.

No memory is allocated unless the new object does not fit within the already allocated memory block.

Source

pub fn take(boxed: Self) -> (T, RecycleBox<()>)

Consumes the box and return both the old value and a box containing an empty tuple.

This is functionally equivalent to calling RecycleBox::replace with an empty tuple as argument, but is more explicit when the intent is specifically to take the contained object while preserving the allocated memory for further re-use. It may also be slightly more efficient.

Source

pub fn pin(x: T) -> Pin<RecycleBox<T>>

Constructs a new Pin<RecycleBox<T>>. If T does not implement Unpin, then x will be pinned in memory and unable to be moved.

Source §

impl<T> RecycleBox<T>
where T: ?Sized,

Source

pub fn recycle(boxed: Self, x: U) -> RecycleBox ⓘ

Consumes the box and creates another one, re-using if possible the already allocated memory.

The current boxed object is dropped. No memory is allocated unless the new object does not fit within the already allocated memory block.

Source

pub fn vacate(boxed: Self) -> RecycleBox<()> ⓘ

Consumes the box and creates another one containing an empty tuple.

This is functionally equivalent to calling RecycleBox::recycle with an empty tuple as argument, but is more explicit when the intent is specifically to drop the contained object while preserving the allocated memory for further re-use. It may also be slightly more efficient.

Source

pub fn recycle_pinned(boxed: Pin<RecycleBox<T>>, x: U) -> RecycleBox ⓘ

Consumes a pinned box and creates another box, re-using if possible the already allocated memory.

This is the same as RecycleBox::recycle but for a pinned RecycleBox. The Pin contract is upheld since the current object is dropped before it is replaced by the new object.

§Example

use std::pin::Pin;
use recycle_box::RecycleBox;

let pinned_box: Pin<_> = RecycleBox::new(42).into();
let new_box = RecycleBox::recycle_pinned(pinned_box, "Forty two");

Source

pub fn vacate_pinned(boxed: Pin<RecycleBox<T>>) -> RecycleBox<()> ⓘ

Consumes a pinned box and creates another box containing an empty tuple.

This is the same as RecycleBox::vacate but for a pinned RecycleBox. The Pin contract is upheld since the current object is dropped before it is replaced by an empty tuple.

§Example

use std::pin::Pin;
use recycle_box::RecycleBox;

let pinned_box: Pin<_> = RecycleBox::new(42).into();
let empty_box = RecycleBox::vacate_pinned(pinned_box);

Source

pub fn into_pin(boxed: Self) -> Pin<Self>

Converts a RecycleBox<T> into a Pin<RecycleBox<T>>. If T does not implement Unpin, then *boxed will be pinned in memory and unable to be moved.

This conversion does not allocate on the heap and happens in place.

Source

pub unsafe fn from_raw_parts( ptr: mut T, base_ptr: mut u8, layout: Layout, ) -> Self

Constructs a box from raw pointers and a layout.

The T object pointed to and the storage defined by the base pointer and the layout become owned by the resulting RecycleBox.

§Safety

The caller is responsible for making sure that the object pointed to exists, is of the proper type and is within an already allocated memory block consistent with the specified base pointer and layout. Also, the user must ensure that ownership of the object and of the allocated memory is exclusively held by the box.

Source