Struct Blink

pub struct Blink<A = BlinkAlloc<Global>> { /* private fields */ }

An allocator adaptor for designed for blink allocator. Provides user-friendly methods to emplace values into allocated memory. Supports emplace existing, constructing value in allocated memory directly or indirectly. And also emplacing items yield from iterator into contiguous memory and returning slice reference.

Blink calls Drop::drop for emplaced values when reset or dropped. This allows to use Blink instead of collections in some scenarios without needing to enable allocation_api feature.

A blink-allocator adapter for user-friendly safe allocations without use of collections.

Provides an ability to emplace values into allocated memory, baked by the associated blink-allocator instance. And returns mutable reference to the value. Values can be emplaced by move, by construction in allocated memory (when compiler likes us), from iterators etc. Most operations are provided in two flavors: try_ prefixed methods returns Result with allocation errors. And non-prefixed methods calls handle_alloc_error method (unless “alloc” feature is not enabled, in this case it panics). Non-prefixed methods require “no_global_oom_handling” feature cfg is disabled.

Blink can be reset by calling reset method. It drops all emplaced values and resets associated allocator instance. If allocator instance is shared, resetting it will have no effect.

Implementations

impl Blink<BlinkAlloc<Global>>

pub const fn new() -> Self

Creates new blink instance with BlinkAlloc baked by Global allocator.

Examples

use blink_alloc::Blink;
let mut blink = Blink::new();

blink.put(42);

pub const fn with_chunk_size(capacity: usize) -> Self

Creates new blink instance with BlinkAlloc baked by Global allocator. BlinkAlloc receives starting chunk size.

Examples

use blink_alloc::Blink;
let mut blink = Blink::with_chunk_size(16);

blink.put(42);

impl<A> Blink<A>

pub const fn new_in(alloc: A) -> Self

Creates new blink instance with provided allocator instance.

pub fn allocator(&self) -> &A

Returns reference to allocator instance.

pub fn drop_all(&mut self)

Drops all allocated values.

Prefer to use reset method if associated allocator instance supports it.

impl<A> Blink<A>

where A: BlinkAllocator,

pub fn reset(&mut self)

Drops all allocated values. And resets associated allocator instance.

impl<A> Blink<A>

where A: BlinkAllocator,

pub fn put<T: 'static>(&self, value: T) -> &mut T

Puts value into this Blink instance. Returns reference to the value.

Effectively extends lifetime of the value from local scope to the reset scope.

For more flexible value placement see Blink::emplace, Blink::emplace_no_drop and Blink::emplace_unchecked.

Example

let mut blink = Blink::new();
let foo = blink.put(42);
assert_eq!(*foo, 42);
*foo = 24;
blink.reset();
// assert_eq!(*foo, 24); // Cannot compile. `foo` does not outlive reset.

pub fn put_no_drop<T>(&self, value: T) -> &mut T

Puts value into this Blink instance. Returns reference to the value.

The value will not be dropped when Blink is reset.

Effectively extends lifetime of the value from local scope to the reset scope.

For more flexible value placement see Blink::emplace, Blink::emplace_no_drop and Blink::emplace_unchecked.

Example

let mut blink = Blink::new();
let foo = blink.put(42);
assert_eq!(*foo, 42);
*foo = 24;
blink.reset();
// assert_eq!(*foo, 24); // Cannot compile. `foo` does not outlive reset.

pub fn try_uninit<T>(&self) -> Option<&mut MaybeUninit<T>>

Allocates memory for a value. Returns some reference to the uninitialized value. If allocation fails, returns none.

pub fn uninit<T>(&self) -> &mut MaybeUninit<T>

Allocates memory for a value. Returns reference to the uninitialized value.

pub fn copy_slice<T>(&self, slice: &[T]) -> &mut [T]

where T: Copy,

Copies the slice to the allocated memory and returns reference to the new slice.

pub fn try_copy_slice<T>(&self, slice: &[T]) -> Option<&mut [T]>

where T: Copy,

Allocates memory for a copy of the slice. Copies the slice to the allocated memory and returns reference to the new slice. If allocation fails, returns None.

pub fn copy_str(&self, string: &str) -> &mut str

Copies the slice to the allocated memory and returns reference to the new slice.

pub fn try_copy_str(&self, string: &str) -> Option<&mut str>

Allocates memory for a copy of the slice. Copies the slice to the allocated memory and returns reference to the new slice. If allocation fails, returns None.

pub fn emplace<T: 'static>(&self) -> Emplace<'_, A, T>

Returns an Emplace adaptor that can emplace values into the blink allocator.

This version requires the value type to be 'static. To use with non-static types consider using one of the following:

• Blink::emplace_no_drop Causes emplaced value to not be dropped on reset. Avoiding potential unsoundness in Drop implementation.
• Blink::emplace_shared Returns shared reference to emplaced values.
• Blink::emplace_unchecked Unsafe version of emplace. User must guarantee that the value won’t have access to references allocated by the blink allocator later.

Example

let mut blink = Blink::new();
let foo = blink.put(42);
assert_eq!(*foo, 42);
*foo = 24;
blink.reset();
// assert_eq!(*foo, 24); // Cannot compile. `foo` does not outlive reset.

pub fn emplace_no_drop<T>(&self) -> Emplace<'_, A, T>

Returns an Emplace adaptor that can emplace values into the blink allocator.

This version causes emplaced value to be not-dropped on reset. To drop returned value on reset, consider one of the following:

• Blink::emplace Requires the value type to be 'static.
• Blink::emplace_shared Returns shared reference to emplaced values.
• Blink::emplace_unchecked Unsafe version of emplace. User must guarantee that the value won’t have access to references allocated by the blink allocator later.

Example

struct Foo<'a>(&'a String);

impl Drop for Foo<'_> {
    fn drop(&mut self) {
        println!("{}", self.0);
    }
}

let mut blink = Blink::new();
let s = "Hello".to_owned();
let foo = blink.emplace_no_drop().value(Foo(&s));
assert_eq!(foo.0, "Hello");
let world = blink.put("World".to_owned());
// Would be unsound if `foo` could be dropped.
foo.0 = world;
blink.reset();
// assert_eq!(foo.0, "Universe"); // Cannot compile. `foo` does not outlive reset.

pub fn emplace_shared<T>(&self) -> Emplace<'_, A, T, &T, &[T]>

Returns an Emplace adaptor that can emplace values into the blink allocator.

This version returns shared references to emplaced values. Lifts the 'static requirement. Still allows emplaced values to be dropped on reset.

To drop returned value on reset, consider one of the following:

• Blink::emplace Requires the value type to be 'static.
• Blink::emplace_no_drop Causes emplaced value to not be dropped on reset. Avoiding potential unsoundness in Drop implementation.
• Blink::emplace_unchecked Unsafe version of emplace. User must guarantee that the value won’t have access to references allocated by the blink allocator later.

struct Foo<'a>(&'a String);

impl Drop for Foo<'_> {
    fn drop(&mut self) {
        println!("{}", self.0);
    }
}

let mut blink = Blink::new();
let s = "Hello".to_owned();
let foo = blink.emplace_no_drop().value(Foo(&s));
assert_eq!(foo.0, "Hello");
let world = blink.put("World".to_owned());
// Would be unsound if `foo` was mutable.
// foo.0 = world;
blink.reset();
// assert_eq!(foo.0, "Universe"); // Cannot compile. `foo` does not outlive reset.

pub unsafe fn emplace_unchecked<T>(&self) -> Emplace<'_, A, T>

Returns an Emplace adaptor that can emplace values into the blink allocator.

This is unsafe version of Blink::emplace. User must guarantee that values won’t attempt to access memory allocated by the blink allocator later in their Drop::drop For safe code consider using one of the following:

• Blink::emplace Requires the value type to be 'static.
• Blink::emplace_no_drop Causes emplaced value to not be dropped on reset. Avoiding potential unsoundness in Drop implementation.
• Blink::emplace_shared Returns shared reference to emplaced values.

Safety

Avoid incorrect usage. See below.

Incorrect usage example

Other emplace methods are safe as they guarantee following case is impossible.

struct Foo<'a>(&'a String);

impl Drop for Foo<'_> {
    fn drop(&mut self) {
        println!("{}", self.0);
    }
}

let mut blink = Blink::new();
let s = "Hello".to_owned();
let foo = blink.emplace_no_drop().value(Foo(&s));
assert_eq!(foo.0, "Hello");
let world = blink.put("World".to_owned());
// Unsound since `foo` would access `world` in `Drop`
// and `world` is dropped earlier.
foo.0 = world;
blink.reset();
// assert_eq!(foo.0, "Universe"); // Cannot compile. `foo` does not outlive reset.

Trait Implementations

impl<A> Default for Blink<A>

where A: Default,

fn default() -> Self

Returns the “default value” for a type.

impl<A> Send for Blink<A>

where A: Send,