Struct emplacable::Emplacer
source · #[repr(transparent)]pub struct Emplacer<'a, T>(_)
where
T: ?Sized;
Expand description
Passed as the last argument to Emplacable
closures.
Wraps a closure that tells the function where to write its return value.
You won’t need to interact with this type directly unless you are writing a function
that directly produces or consumes Emplacable
s.
An Emplacer
closure generally does one of three things:
- Allocate memory with the layout of its first argument, run the closure it receives
as its third argument with a pointer to the start of the allocation, then constructs a pointer
of type
T
to that allocation with the given metadata. - Run the closure it recieves with a null pointer to signal that the value of type
T
should be dropped in place. - Do nothing at all, signifying that the value of type
T
should be forgotten and its desctructor should not be run.
Emplacer
s are allowed to panic, unwind, abort, etc. However, they can’t unwind after
they have run their inner closure.
Implementations§
source§impl<'a, T> Emplacer<'a, T>where
T: ?Sized,
impl<'a, T> Emplacer<'a, T>where T: ?Sized,
sourcepub unsafe fn from_fn<'b>(
emplacer_fn: &'b mut EmplacerFn<'a, T>
) -> &'b mut Self
pub unsafe fn from_fn<'b>( emplacer_fn: &'b mut EmplacerFn<'a, T> ) -> &'b mut Self
Creates an Emplacer
from an EmplacerFn<T>
closure
(a dyn FnMut(Layout, <T as Pointee>::Metadata, &mut dyn FnMut(*mut PhantomData<T>))
).
emplacer_fn
should do one the following things:
- Allocate a chunk of memory that satisfies the requirements of the
Layout
it receives as its fisrst argument, and pass a pointer to the start of that allocation to the closure it recieves as its third argument. - Ignore its first and second arguments, and pass a null pointer to the closure as its first argument.
- Do nothing at all.
Safety
The emplacer_fn
, if it runs the closure that it recieves as a third argument, must
pass in a pointer that is ether null, or has the alignment of the Layout
passed to it,
and is valid for writes of the number of bytes corresponding to the Layout
.
emplacer_fn
is not permitted to run the closure it receives as its third argument more than once.
If emplacer_fn
runs the closure it receives as its thrid argument, it must do so before returning.
emplacer_fn
is allowed to unwind or otherwise diverge. But if it runs the closure it receives as its third argument,
then once that inner closure returns, emplacer_fn
is no longer allowed to unwind.
The emplacer_fn
can’t assume that is has received full ownership of
the value written to the pointer of the inner closure, until the moment emplacer_fn
(and the EmplacableFn<T>
that calls it) returns. Specifically, emplacer_fn
is not
allowed to drop the value.
sourcepub unsafe fn into_fn<'b>(&'b mut self) -> &'b mut EmplacerFn<'a, T>
pub unsafe fn into_fn<'b>(&'b mut self) -> &'b mut EmplacerFn<'a, T>
Obtains the closure inside this Emplacer<T>
.
This should generally be called only inside EmplacableFn<T>
s.
Safety
If you call the resulting EmplacerFn
closure, you must ensure
that the closure you pass in:
- If it receives a non-null pointer as an argument, it must write a valid value of type
T
to the passed-in pointer. This value must correspond to theLayout
and pointer metadata you passed to theEmplacerFn<T>
. - If it recieves a null pointer as an argument, then it is recommmended that you drop the
value of type
T
that you would have written out had the pointer been non-null. (you aren’t required to do this.) - In either case, the closure is alterately allowed to panic, unwind, abort, or diverge in some other way. If it does so, it is not obligated to perform the tasks listed above.
If T
’s size or alignment can be known at compile-time, or can be determined from the
pointer metadata alone, and you pass in an oversized/overaligned Layout
, then you are not guaranteed
to get an allocation that matches the Layout
’s stronger guarantees.
You may not call the EmplacerFn
closure more than once.