Struct GlobalBlinkAlloc

Source

pub struct GlobalBlinkAlloc<A: Allocator = System> { /* private fields */ }

Expand description

GlobalAlloc implementation based on SyncBlinkAlloc.

§Example

use blink_alloc::GlobalBlinkAlloc;

#[global_allocator]
static GLOBAL_ALLOC: GlobalBlinkAlloc = GlobalBlinkAlloc::new();

fn main() {
    let _ = Box::new(42);
    let _ = vec![1, 2, 3];
}

Implementations§

Source §

impl GlobalBlinkAlloc<System>

Source

pub const fn new() -> Self

Create a new GlobalBlinkAlloc.

Const function can be used to initialize a static variable.

§Example

use blink_alloc::GlobalBlinkAlloc;

#[global_allocator]
static GLOBAL_ALLOC: GlobalBlinkAlloc = GlobalBlinkAlloc::new();

fn main() {
    let _ = Box::new(42);
    let _ = vec![1, 2, 3];
}

Source

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

Create a new GlobalBlinkAlloc.

This method allows to specify initial chunk size.

Const function can be used to initialize a static variable.

§Example

use blink_alloc::GlobalBlinkAlloc;

#[global_allocator]
static GLOBAL_ALLOC: GlobalBlinkAlloc = GlobalBlinkAlloc::new();

fn main() {
    let _ = Box::new(42);
    let _ = vec![1, 2, 3];
}

Source §

impl<A> GlobalBlinkAlloc<A>
where A: Allocator,

Source

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

Create a new GlobalBlinkAlloc with specified underlying allocator.

Const function can be used to initialize a static variable.

§Example

use blink_alloc::GlobalBlinkAlloc;

#[global_allocator]
static GLOBAL_ALLOC: GlobalBlinkAlloc<std::alloc::System> = GlobalBlinkAlloc::new_in(std::alloc::System);

fn main() {
    let _ = Box::new(42);
    let _ = vec![1, 2, 3];
}

Source

pub const fn with_chunk_size_in(chunk_size: usize, allocator: A) -> Self

Create a new GlobalBlinkAlloc with specified underlying allocator.

This method allows to specify initial chunk size.

Const function can be used to initialize a static variable.

§Example

use blink_alloc::GlobalBlinkAlloc;

#[global_allocator]
static GLOBAL_ALLOC: GlobalBlinkAlloc<std::alloc::System> = GlobalBlinkAlloc::new_in(std::alloc::System);

fn main() {
    let _ = Box::new(42);
    let _ = vec![1, 2, 3];
}

Source

pub unsafe fn reset(&self)

Resets this allocator, deallocating all chunks except the last one. Last chunk will be reused. With steady memory usage after few iterations one chunk should be sufficient for all allocations between resets.

§Safety

Memory allocated from this allocator in blink mode becomes invalidated. The user is responsible to ensure that previously allocated memory won’t be used after reset.

§Example

use blink_alloc::UnsafeGlobalBlinkAlloc;

#[global_allocator]
static GLOBAL_ALLOC: UnsafeGlobalBlinkAlloc = unsafe { UnsafeGlobalBlinkAlloc::new() };

unsafe { GLOBAL_ALLOC.blink_mode() };

let b = Box::new(42);
let v = vec![1, 2, 3];
drop(b);
drop(v);

// Safety: memory allocated in blink mode won't be used after reset.
unsafe {
    GLOBAL_ALLOC.reset();
    GLOBAL_ALLOC.direct_mode();
};

Source

pub unsafe fn blink_mode(&self)

Switches allocator to blink mode. All allocations will be served by blink-allocator.

The type is created in direct mode. When used as global allocator, user may manually switch into blink mode in main or at any point later.

However user must switch back to direct mode before returning from main.

§Safety

Must be externally synchronized with other threads accessing this allocator. Memory allocated in direct mode must not be deallocated while in blink mode.

Source

pub unsafe fn direct_mode(&self)

Switches allocator to direct mode. All allocations will be served by underlying allocator.

The type is created in direct mode. When used as global allocator, user may manually switch into blink mode in main or at any point later.

However user must switch back to direct mode before returning from main.

§Safety

Must be externally synchronized with other threads accessing this allocator. Memory allocated in blink mode must not be deallocated while in direct mode.

Source

pub fn local(&self) -> LocalBlinkAlloc<'_, A>

Creates a new thread-local blink allocator proxy that borrows from this multi-threaded allocator.

The local proxy allocator works faster and allows more consistent memory reuse. It can be recreated without resetting the multi-threaded allocator, allowing SyncBlinkAlloc to be warm-up and serve all allocations from a single chunk without ever blocking.

Best works for fork-join style of parallelism. Create a local allocator for each thread/task. Reset after all threads/tasks are finished.

§Examples

static BLINK: GlobalBlinkAlloc = GlobalBlinkAlloc::new();

for _ in 0..3 {
    for i in 0..16 {
        let mut blink = BLINK.local(); // Sendable and 'static.
        std::thread::scope(move |_| {
            let mut vec = Vec::new_in(&blink);
            vec.push(i);
            for j in i*2..i*30 {
                vec.push(j); // Proxy will allocate enough memory to grow vec without reallocating on 2nd iteration and later.
            }
            drop(vec); // Without this line it will fail to borrow mutable on next line.
            blink.reset();
        });

        // Safety: Proxies and allocations are dropped.
        unsafe { BLINK.reset() };
    }
}