[Docs] box doesn't contain documentation regarding ZSTs

[naim94a]

I've recently learned that Box::new on a ZST returns the ZSTs alignment. I assumed that the return value didn't really matter since it's a ZST.
This should be added to Box's documentation (Box::from_raw should also be aligned then, right?)

[pnkfelix]

Demo of what is being described:

#[repr(align(1))] struct Align1;
#[repr(align(2))] struct Align2;
#[repr(align(4))] struct Align4;
#[repr(align(8))] struct Align8;

fn main() {
    let a1 = Box::new(Align1);
    let a2 = Box::new(Align2);
    let a4 = Box::new(Align4);
    let a8 = Box::new(Align8);
    
    let p1 = &*a1 as *const _ as usize;
    let p2 = &*a2 as *const _ as usize;
    let p4 = &*a4 as *const _ as usize;
    let p8 = &*a8 as *const _ as usize;
    
    assert_eq!((p1, p2, p4, p8), (1, 2, 4, 8));
}

[pnkfelix]

(However, I don't know if we actually guarantee this behavior, and therefore do not know if we want it documented?)

Update: More specifically: The returned "address" does conform to the specified alignment. But I don't know if want to specify any details about what the address is, beyond the fact that it will conform to the given alignment (and thus the corresponding low-order bits will be zero).

[naim94a]

Documenting requirements for Box::from_raw are probably more important. I don't think users would need to inspect the return value from a Box::new.

We need to know the requirements for the address provided to Box::from_raw. Does it have to be aligned? Is the pointer ignored? (It seems that it is...) Is this valid?

#[repr(align(8))] struct Align8;

fn main() {
    let _: Box<Align8> = unsafe { Box::from_raw(3 as *mut _) };
    let _: Box<Align8> = unsafe { Box::from_raw(0 as *mut _) };
}

[pnkfelix]

Okay, I can see the motivation for adding more explanation somewhere.

Its possible the right place for it would be in the Memory Layout documentation for std::boxed ?

[pnkfelix]

(but also, its possible that the guarantees we want are precisely the little amount we currently say in the "Memory Layout"...)

[pwnorbitals]

I agree that documenting Box::from_raw (https://doc.rust-lang.org/std/boxed/struct.Box.html#method.from_raw) is probably higher priority. Calling it with wrongly aligned address should be documented as undefined behaviour imo

[hkBst]

Current docs say (when talking about converting between Box and pointer): "For zero-sized values, the Box pointer has to be non-null and sufficiently aligned. The recommended way to build a Box to a ZST if Box::new cannot be used is to use ptr::NonNull::dangling." This is at https://doc.rust-lang.org/nightly/std/boxed/index.html#memory-layout which is linked to from https://doc.rust-lang.org/nightly/std/boxed/struct.Box.html#method.from_raw.

Also

#[repr(align(8))] struct Align8;

fn main() {
    let _: Box<Align8> = unsafe { Box::from_raw(3 as *mut _) }; // needs Miri
    let _: Box<Align8> = unsafe { Box::from_raw(0 as *mut _) }; // <== panics here in debug
}

results in:
thread 'main' panicked at core/src/panicking.rs:223:5:
unsafe precondition(s) violated: NonNull::new_unchecked requires that the pointer is non-null

The first box requires Miri to detect, which is surprising:

1060 |         unsafe { Self::from_raw_in(raw, Global) }
     |                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ constructing invalid value: encountered an unaligned box (required 8 byte alignment but found 1)
     |