Struct windows_permissions::localheap::LocalBox [−][src]
pub struct LocalBox<T> { /* fields omitted */ }
Expand description
A smart pointer to an object on the local heap.
Windows has several different options for allocation, and the local heap is
no longer recommended. However, several of the
WinAPI calls in this crate use the local heap, allocating with LocalAlloc
and freeing with LocalFree
. This type encapsulates that behavior,
representing objects that reside on the local heap.
It is primarily created using unsafe
code in the wrappers
crate when
the WinAPI allocates a data structure for the program (using from_raw
).
However, allocations can be manually made with allocate
or try_allocate
.
For example:
use std::mem::size_of; use windows_permissions::LocalBox; let mut local_ptr1: LocalBox<u32> = unsafe { LocalBox::allocate() }; let mut local_ptr2: LocalBox<u32> = unsafe { LocalBox::try_allocate(true, size_of::<u32>()).unwrap() }; *local_ptr1 = 5u32; *local_ptr2 = 5u32; assert_eq!(local_ptr1, local_ptr2);
For details, see MSDN.
Exotically-sized types
This struct has not been tested with exotically-sized types. Use with extreme caution.
Implementations
Get a LocalBox
from a NonNull
Safety
- The
NonNull
pointer must have been allocated with a Windows API call. When the resultingNonNull<T>
is dropped, it will be dropped withLocalFree
- The buffer pointed to by the pointer must be a valid
T
Allocate enough zeroed memory to hold a T
with LocalAlloc
The memory will always come back zeroed, which has a modest performance penalty but can reduce the impact of buffer overruns.
Panics
Panics if the underlying LocalAlloc
call fails.
Safety
The allocated memory is zeroed, which may not be a valid representation
of a T
.
Allocate memory with LocalAlloc
If the allocation fails, returns the error code.
Safety
The contents of the memory are not guaranteed to be a valid T
. The
contents will either be zeroed or uninitialized depending on the zeroed
parameter.
Additionally, size
should be large enough to contain a T
.
Trait Implementations
Auto Trait Implementations
impl<T> RefUnwindSafe for LocalBox<T> where
T: RefUnwindSafe,
impl<T> UnwindSafe for LocalBox<T> where
T: RefUnwindSafe,
Blanket Implementations
Mutably borrows from an owned value. Read more