Struct r_efi_alloc::global::Bridge

pub struct Bridge { /* private fields */ }

Bridge for Global Allocators

This bridge connects static allocator variables to the dynamic UEFI allocator interfaces. The bridge object implements the GlobalAlloc interface and can thus be marked as global_allocator.

The need for a bridge arises from the fact that UEFI requires access to the system-table to allocate memory, and the system-table is only available as argument to the entry-point. Hence, this bridge represents a dynamic link between the global allocator and a runtime allocator created by the application.

The main API of the bridge is the attach() function, which allows to attach an allocator to the bridge, which is thereon used for allocations. Only a single allocator can be attached to a bridge at a time, and any global allocations will fail if no allocator is attached.

The attach() operation returns an object that represents the attachment. To release it, the attachment object has to be dropped. Note that the caller must ensure that any global allocator is released before an allocator attachment is released.

Implementations

impl Bridge

pub const fn new() -> Bridge

Create Bridge

The Bridge type represents the global allocator. Since the latter cannot be instantiated at compile-time (on UEFI the system-table address can only be resolved at runtime, since it is passed as argument to the entry point), it is implemented as a bridge between the actual allocator object and the global allocator. By default, the bridge object has no allocator linked. Any allocation requests will thusly yield an allocation error.

To make use of a bridge, you have to instantiate an allocator object and attach it via the attach() method.

You can create as many bridges as you like. However, to mark a bridge as global allocator, you have to make it a global, static variable and annotate it with #[global_allocator]. Only one such variable is allowed to exist in any crate tree, and it must be declared in the root module of a given crate.

pub unsafe fn attach<'alloc, 'bridge>(
    &'bridge self,
    allocator: &'alloc mut Allocator
) -> Option<Attachment<'alloc, 'bridge>>

Attach an allocator

This attaches the allocator given as @allocator to the bridge. If there is an allocator attached already, this will yield None. Otherwise, an attachment is returned that represents this link. Dropping the attachment will detach the allocator from the bridge.

As long as an allocator is attached to a bridge, allocations through this bridge (via rust’s GlobalAlloc trait) will be served by this allocator.

This is an unsafe interface. It is the caller’s responsibility to guarantee that the attachment survives all outstanding allocations. That is, any allocated memory must be released before detaching the allocator.

Trait Implementations

impl GlobalAlloc for Bridge

unsafe fn alloc(&self, layout: Layout) -> *mut u8

Allocate memory as described by the given layout.

unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout)

Deallocate the block of memory at the given ptr pointer with the given layout.

unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8

Behaves like alloc, but also ensures that the contents are set to zero before being returned.

unsafe fn realloc(&self, ptr: *mut u8, layout: Layout, new_size: usize) -> *mut u8

Shrink or grow a block of memory to the given new_size. The block is described by the given ptr pointer and layout.