Documentation for addr_of_mut! is contradictory

[nicholasbishop]

The documentation for addr_of_mut! says:

Note, however, that the expr in addr_of_mut!(expr) is still subject to all the usual rules. In particular, addr_of_mut!(*ptr::null_mut()) is Undefined Behavior because it dereferences a null pointer.

However, in the example for Creating a pointer to uninitialized data it shows this code:

let f1_ptr = unsafe { ptr::addr_of_mut!((*uninit.as_mut_ptr()).field) };

In that example it appears as though expr contains a dereference of uninitialized data, which is not normally valid. That seems in conflict with the earlier warning that "all the usual rules" apply.

I'm guessing that maybe dereferencing is allowed in expr as long as the pointer isn't dangling?

[RalfJung]

In that example it appears as though expr contains a dereference of uninitialized data, which is not normally valid.

Why do you think that is the case?
"Dereferencing" (as in, creating a place from) a pointer to uninitialized memory is fine. Only actually reading from that place is a problem (it depends on the type, some types allow uninit memory -- like MaybeUninit<u64> -- and others do not).

[nicholasbishop]

Thanks, I didn't realize that was allowed. Getting a good handle on what is and isn't allowed with pointers in Rust is not always super easy :)

Is there an existing piece of documentation that spells out what all the rules are? It would be great to hyperlink all the usual rules to that documentation, or just directly list out what the rules are inline if they are sufficiently short.

[RalfJung]

Yeah, it's all kind of complicated. ;)

Basically the core rules are these ones.

[nicholasbishop]

Closing this. I think #114902 covers it pretty well :)