Struct storages::boxed::RawBox

pub struct RawBox<T, B: ?Sized = AllocatedBuffer<T>> where
    T: ?Sized,
    B: Buffer<T>,  { /* fields omitted */ }

A thin wrapper around a buffer.

RawBox<T, B> abstracts over a Buffer, which holds values of T. As a buffer may need external data, every operation on RawBox, which communicates with the underlying buffer, requires the external data to be passed. For an AllocatedBuffer<T, A> this means, that A has to be passed as a reference. For this reason, RawBox only implements Deref and DerefMut when B::ExternalData is ().

Note, that RawBox does not implement Drop so it must be cleaned up after usage.

When storing the data next to the storage is not an issue, Box should be used instead.

Examples

Allocating a RawBox in the system allocator:

#![feature(allocator_api)]

use std::alloc::System;
use storages::{boxed::RawBox, buffer::AllocatedBuffer};

let buffer = AllocatedBuffer::new_in(&System)?;
let five = RawBox::new_in(5, buffer, &System);

assert_eq!(*five.as_ref(&System), 5);

five.free(&System);

When using a buffer, which doesn't require external data, the usage is similar to Box:

use std::mem;
use storages::boxed::RawBox;

let buffer = [mem::MaybeUninit::<u32>::uninit(); 3];
let mut values = RawBox::new_uninit_slice_in(buffer);

let values = unsafe {
    // Deferred initialization:
    values[0].as_mut_ptr().write(1);
    values[1].as_mut_ptr().write(2);
    values[2].as_mut_ptr().write(3);

    values.assume_init()
};

assert_eq!(*values, [1, 2, 3])

Implementations

impl<T> RawBox<T>

Construction of boxed values with a buffer backed by the global allocator.

pub fn new(value: T) -> Self

Allocates memory on the global heap and then places value into it.

This doesn't actually allocate if T is zero-sized.

Examples

#![feature(allocator_api)]

use std::alloc::Global;
use storages::boxed::RawBox;

let five = RawBox::new(5);

assert_eq!(*five.as_ref(&Global), 5);

five.free(&Global);

pub fn new_uninit() -> RawBox<MaybeUninit<T>, AllocatedBuffer<T>>

Constructs a new raw box with uninitialized contents.

Examples

#![feature(allocator_api, new_uninit)]

use std::alloc::Global;
use storages::boxed::RawBox;

let mut five = RawBox::<u32>::new_uninit();

let five = unsafe {
    // Deferred initialization:
    five.as_mut(&Global).as_mut_ptr().write(5);

    five.assume_init()
};

assert_eq!(*five.as_ref(&Global), 5);

five.free(&Global);

pub fn new_zeroed() -> RawBox<MaybeUninit<T>, AllocatedBuffer<T>>

Constructs a new raw box with uninitialized contents, with the memory being filled with 0 bytes.

See MaybeUninit::zeroed for examples of correct and incorrect usage of this method.

Examples

#![feature(allocator_api, new_uninit)]

use std::alloc::Global;
use storages::boxed::RawBox;

let zero = RawBox::<u32>::new_zeroed();
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero.as_ref(&Global), 0);

zero.free(&Global);

impl<T> RawBox<[T]>

Construction of boxed slices with a buffer backed by the global allocator.

pub fn new_uninit_slice(
    len: usize
) -> RawBox<[MaybeUninit<T>], AllocatedBuffer<[T]>>

Constructs a boxed slice with uninitialized contents.

Examples

#![feature(allocator_api, maybe_uninit_extra)]

use std::alloc::Global;
use storages::boxed::RawBox;

let mut values = RawBox::new_uninit_slice(3);

let values = unsafe {
    // Deferred initialization:
    values.as_mut(&Global)[0].write(1);
    values.as_mut(&Global)[1].write(2);
    values.as_mut(&Global)[2].write(3);

    values.assume_init()
};

assert_eq!(*values.as_ref(&Global), [1, 2, 3]);

values.free(&Global);

pub fn new_zeroed_slice(
    len: usize
) -> RawBox<[MaybeUninit<T>], AllocatedBuffer<[T]>>

Constructs a boxed with uninitialized contents with the memory being filled with 0 bytes.

See MaybeUninit::zeroed for examples of correct and incorrect usage of this method.

Examples

#![feature(allocator_api, maybe_uninit_extra)]

use std::alloc::Global;
use storages::boxed::RawBox;

let values = RawBox::<[u32]>::new_zeroed_slice(3);
let values = unsafe { values.assume_init() };

assert_eq!(*values.as_ref(&Global), [0, 0, 0]);

values.free(&Global);

impl<T, B> RawBox<T, B> where
    B: Buffer<T>, 

Construction of boxed values in a provided buffer.

pub fn new_in(value: T, buffer: B, data: &B::ExternalData) -> Self

Places the value in the provided buffer.

Examples

#![feature(allocator_api)]

use std::alloc::System;
use storages::{boxed::RawBox, buffer::AllocatedBuffer};

let buffer = AllocatedBuffer::new_in(&System)?;
let five = RawBox::new_in(5, buffer, &System);

assert_eq!(*five.as_ref(&System), 5);

five.free(&System);

pub fn new_uninit_in(buffer: B) -> RawBox<MaybeUninit<T>, B> where
    B: Buffer<MaybeUninit<T>>, 

Constructs a new raw box with uninitialized contents in the provided buffer.

Examples

#![feature(allocator_api, maybe_uninit_extra)]

use std::alloc::System;
use storages::{boxed::RawBox, buffer::AllocatedBuffer};

let buffer = AllocatedBuffer::new_in(&System)?;
let mut five = RawBox::<u32, _>::new_uninit_in(buffer);

let five = unsafe {
    // Deferred initialization:
    five.as_mut(&System).write(5);

    five.assume_init()
};

assert_eq!(*five.as_ref(&System), 5);

five.free(&System);

impl<T, B> RawBox<[T], B> where
    B: Buffer<[T]>, 

Construction of boxed slices in a provided buffer.

pub fn new_uninit_slice_in(buffer: B) -> RawBox<[MaybeUninit<T>], B> where
    B: Buffer<[MaybeUninit<T>]>, 

Constructs a boxed with uninitialized contents in the provided buffer.

Examples

use std::mem;
use storages::boxed::RawBox;

let buffer = [mem::MaybeUninit::<u32>::uninit(); 3];
let mut values = RawBox::new_uninit_slice_in(buffer);

let values = unsafe {
    // Deferred initialization:
    values[0].as_mut_ptr().write(1);
    values[1].as_mut_ptr().write(2);
    values[2].as_mut_ptr().write(3);

    values.assume_init()
};

assert_eq!(*values, [1, 2, 3]);

impl<T, B> RawBox<MaybeUninit<T>, B> where
    B: Buffer<T> + Buffer<MaybeUninit<T>>, 

pub unsafe fn assume_init(self) -> RawBox<T, B>

Converts to RawBox<T, B>.

Safety

As with MaybeUninit::assume_init, it is up to the caller to guarantee that the value really is in an initialized state. Calling this when the content is not yet fully initialized causes immediate undefined behavior.

Examples

#![feature(allocator_api, maybe_uninit_extra, new_uninit)]

use std::alloc::Global;
use storages::boxed::RawBox;

let mut five = RawBox::<u32>::new_uninit();

let five = unsafe {
    // Deferred initialization:
    five.as_mut(&Global).write(5);

    five.assume_init()
};

assert_eq!(*five.as_ref(&Global), 5);

five.free(&Global);

impl<T, B> RawBox<[MaybeUninit<T>], B> where
    B: Buffer<[T]> + Buffer<[MaybeUninit<T>]>, 

pub unsafe fn assume_init(self) -> RawBox<[T], B>

Constructs a boxed with uninitialized contents in the provided buffer.

Safety

As with MaybeUninit::assume_init, it is up to the caller to guarantee that the value really is in an initialized state. Calling this when the content is not yet fully initialized causes immediate undefined behavior.

Examples

use std::mem;
use storages::boxed::RawBox;

let buffer = [mem::MaybeUninit::<u32>::uninit(); 3];
let mut values = RawBox::new_uninit_slice_in(buffer);

let values = unsafe {
    // Deferred initialization:
    values[0].as_mut_ptr().write(1);
    values[1].as_mut_ptr().write(2);
    values[2].as_mut_ptr().write(3);

    values.assume_init()
};

assert_eq!(*values, [1, 2, 3])

impl<T, B> RawBox<T, B> where
    T: ?Sized,
    B: Buffer<T>, 

pub fn free(self, data: &B::ExternalData) where
    B: UnmanagedBuffer<T>, 

pub fn buffer(&self) -> &B

pub fn buffer_mut(&mut self) -> &mut B

pub fn as_ref(&self, data: &B::ExternalData) -> &T

pub fn as_mut(&mut self, data: &B::ExternalData) -> &mut T

Trait Implementations

impl<T, U, BT, BU> CoerceUnsized<RawBox<U, BU>> for RawBox<T, BT> where
    T: ?Sized,
    U: ?Sized,
    BT: Buffer<T> + CoerceUnsized<BU>,
    BU: Buffer<U>, 

impl<T, B> Deref for RawBox<T, B> where
    T: ?Sized,
    B: Buffer<T, ExternalData = ()>, 

type Target = T

The resulting type after dereferencing.

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

Dereferences the value.

impl<T, B> DerefMut for RawBox<T, B> where
    T: ?Sized,
    B: Buffer<T, ExternalData = ()>, 

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

Mutably dereferences the value.