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 Emplacables.

An Emplacer closure generally does one of three things:

  1. 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.
  2. Run the closure it recieves with a null pointer to signal that the value of type T should be dropped in place.
  3. Do nothing at all, signifying that the value of type T should be forgotten and its desctructor should not be run.

Emplacers 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,

source

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.

source

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 the Layout and pointer metadata you passed to the EmplacerFn<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.

Auto Trait Implementations§

§

impl<'a, T> !RefUnwindSafe for Emplacer<'a, T>

§

impl<'a, T> !Send for Emplacer<'a, T>

§

impl<'a, T> !Sized for Emplacer<'a, T>

§

impl<'a, T> !Sync for Emplacer<'a, T>

§

impl<'a, T> !Unpin for Emplacer<'a, T>

§

impl<'a, T> !UnwindSafe for Emplacer<'a, T>

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more