Trait storage_api::Storage

source · [−]
pub unsafe trait Storage {
    type Handle: Copy + Ord + Hash + Unpin + Send + Sync;

    fn allocate(&mut self, layout: Layout) -> Result<Self::Handle, AllocError>;
    unsafe fn deallocate(&mut self, handle: Self::Handle, layout: Layout);
    unsafe fn resolve(&self, handle: Self::Handle, layout: Layout) -> &Memory;
    unsafe fn resolve_mut(
        &mut self, 
        handle: Self::Handle, 
        layout: Layout
    ) -> &mut Memory;
    unsafe fn grow(
        &mut self, 
        handle: Self::Handle, 
        old_layout: Layout, 
        new_layout: Layout
    ) -> Result<Self::Handle, AllocError>;
    unsafe fn shrink(
        &mut self, 
        handle: Self::Handle, 
        old_layout: Layout, 
        new_layout: Layout
    ) -> Result<Self::Handle, AllocError>;
}
Expand description

Types which can be used to manage memory handles.

The behavior of this trait is refined by traits PinningStorage, MultipleStorage, and SharedMutabilityStorage.

Required Associated Types

The handle which is used to access the stored memory.

(Removing Send + Sync is enticing, as it allows using ptr::NonNull.)

Required Methods

Allocate memory handle in this storage.

The handled memory is not initialized. Any existing handles are invalidated.

(Do we want an allocate_zeroed?)

Deallocate an object handle in this storage.

The handled memory is not required to be valid in any way. The handle is invalidated.

Safety
  • The handle must have been created by this storage, and must not have been invalidated.
  • The layout must be the same as used to allocate the handle.

Resolve a memory handle in this storage to a reference.

Safety
  • The handle must have been created by this storage, and must not have been invalidated.
  • The layout must be the same as used to allocate the handle.

Resolve a memory handle in this storage to a mutable reference.

Safety
  • The handle must have been created by this storage, and must not have been invalidated.
  • The layout must be the same as used to allocate the handle.

Grow a memory handle to a larger size.

If this function succeeds, then the old handle is invalidated and the handled memory has been moved into the new handle. The new length is uninitialized.

(Do we want a grow_zeroed?)

If this function fails, then the old handle is not invalidated and still contains the memory in its state before calling this function.

Safety
  • The handle must have been created by this storage, and must not have been invalidated.
  • old_layout must be the same as used to allocate the handle.
  • new_layout.size() >= old_layout.size().

Note that new_layout.align() is not required to be the same as old_layout.align()

Shrink a memory handle to a smaller size.

If this function succeeds, then the old handle is invalidated and the prefix of the handled memory has been moved into the new handle.

If this function fails, then the old handle is not invalidated and still contains the memory in its state before calling this function.

Safety
  • The handle must have been created by this storage, and must not have been invalidated.
  • old_layout must be the same as used to allocate the handle.
  • new_layout.size() <= old_layout.size().

Note that new_layout.align() is not required to be the same as old_layout.align()

Implementors