#ffi #no-std #macros #lifetime #ownership

no-std moveit

A library for safe, in-place construction of Rust (and C++!) objects

7 releases (breaking)

0.6.0 Jun 15, 2023
0.5.1 Aug 25, 2022
0.5.0 Mar 28, 2022
0.4.0 Jan 26, 2022
0.1.0 Apr 13, 2021

#96 in Rust patterns

Download history 4040/week @ 2023-08-10 5018/week @ 2023-08-17 8339/week @ 2023-08-24 3722/week @ 2023-08-31 5318/week @ 2023-09-07 4729/week @ 2023-09-14 5534/week @ 2023-09-21 8214/week @ 2023-09-28 7007/week @ 2023-10-05 14756/week @ 2023-10-12 12650/week @ 2023-10-19 10008/week @ 2023-10-26 10562/week @ 2023-11-02 6600/week @ 2023-11-09 7815/week @ 2023-11-16 5239/week @ 2023-11-23

31,977 downloads per month
Used in 25 crates (4 directly)

Apache-2.0 OR MIT



A library for safe, in-place construction of Rust (and C++!) objects.

How It Works

moveit revolves around unsafe traits that impose additional guarantees on !Unpin types, such that they can be moved in the C++ sense. There are two senses of "move" frequently used:

  • The Rust sense, which is a blind memcpy and analogous-ish to the C++ "std::is_trivially_moveable` type-trait. Rust moves also render the moved-from object inaccessible.
  • The C++ sense, where a move is really like a mutating Clone operation, which leave the moved-from value accessible to be destroyed at the end of the scope.

C++ also has constructors, which are special functions that produce a new value in a particular location. In particular, C++ constructors may assume that the address of *this will not change; all C++ objects are effectively pinned and new objects must be constructed using copy or move constructors.

The [New], CopyNew, and MoveNew traits bring these concepts into Rust. A [New] is like a nilary FnOnce, except that instead of returning its result, it writes it to a Pin<&mut MaybeUninit<T>>, which is in the "memory may be repurposed" state described in the Pin documentation (i.e., either it is freshly allocated or the destructor was recently run). This allows a [New] to rely on the pointer's address remaining stable, much like *this in C++.

Types that implement CopyNew may be copy-constructed: given any pointer to T: CopyNew, we can generate a constructor that constructs a new, identical T at a designated location. MoveNew types may be move-constructed: given an owning pointer (see DerefMove) to T, we can generate a similar constructor, except that it also destroys the T and the owning pointer's storage.

None of this violates the existing Pin guarantees: moving out of a Pin<P> does not perform a move in the Rust sense, but rather in the C++ sense: it mutates through the pinned pointer in a safe manner to construct a new P::Target, and then destroys the pointer and its contents.

In general, move-constructible types are going to want to be !Unpin so that they can be self-referential. Self-referential types are one of the primary motivations for move constructors.


A constructor is any type that implements [New]. Constructors are like closures that have guaranteed RVO, which can be used to construct a self-referential type in-place. To use the example from the Pin<T> docs:

use std::marker::PhantomPinned;
use std::mem::MaybeUninit;
use std::pin::Pin;
use std::ptr;
use std::ptr::NonNull;

use moveit::new;
use moveit::new::New;
use moveit::moveit;

// This is a self-referential struct because the slice field points to the
// data field. We cannot inform the compiler about that with a normal
// reference, as this pattern cannot be described with the usual borrowing
// rules. Instead we use a raw pointer, though one which is known not to be
// null, as we know it's pointing at the string.
struct Unmovable {
  data: String,
  slice: NonNull<String>,
  _pin: PhantomPinned,

impl Unmovable {
  // Defer construction until the final location is known.
  fn new(data: String) -> impl New<Output = Self> {
    new::of(Unmovable {
      // We only create the pointer once the data is in place
      // otherwise it will have already moved before we even started.
      slice: NonNull::dangling(),
      _pin: PhantomPinned,
    }).with(|this| unsafe {
      let this = this.get_unchecked_mut();
      this.slice = NonNull::from(&this.data);

    // It is also possible to use other `new::` helpers, such as
    // `new::by` and `new::by_raw`, to configure construction behavior.

// The constructor can't be used directly, and needs to be emplaced.
moveit! {
  let unmoved = Unmovable::new("hello".to_string());
// The pointer should point to the correct location,
// so long as the struct hasn't moved.
// Meanwhile, we are free to move the pointer around.
let mut still_unmoved = unmoved;
assert_eq!(still_unmoved.slice, NonNull::from(&still_unmoved.data));

// Since our type doesn't implement Unpin, this will fail to compile:
// let mut new_unmoved = Unmovable::new("world".to_string());
// std::mem::swap(&mut *still_unmoved, &mut *new_unmoved);

// However, we can implement `MoveNew` to allow it to be "moved" again.

The [new] module provides various helpers for making constructors. As a rule, functions which, in Rust, would normally construct and return a value should return impl New instead. This is analogous to have async fns and .iter() functions work.


The example above makes use of the [moveit!()] macro, one of many ways to turn a constructor into a value. moveit gives you two choices for running a constructor:

  • On the stack, using the MoveRef type (this is what [moveit!()] generates).
  • On the heap, using the extension methods from the Emplace trait.

For example, we could have placed the above in a Box by writing Box::emplace(Unmovable::new()).

License: Apache-2.0

This is not an officially supported Google product.