Tracking Issue for raw_ref_macros

[RalfJung]

This is a tracking issue for the macro version of raw_ref_op (#64490).
The feature gate for the issue is #![feature(raw_ref_macros)].

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also uses as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

Steps

• Implement
• Adjust documentation (see instructions on rustc-dev-guide)
• Stabilization PR (see instructions on rustc-dev-guide)

Unresolved Questions

• Are we happy with the macro names? Currently: core::ptr::raw_const!(path)/core::ptr::raw_mut!(path)
• Potentially blocked on docs issue: pub macro defined in submodule is shown at the wrong path #74355 [fixed in Rustdoc: Fix macros 2.0 and built-in derives being shown at the wrong path #77862]

Implementation history

• add raw_ref macros #72279

[jonas-schievink]

rustdoc displays the macro in core::raw_mut https://doc.rust-lang.org/nightly/core/macro.raw_mut.html

[RalfJung]

Sounds like a rustdoc bug, thanks for pointing that out.

Reported as #74355.

[RalfJung]

Stabilization report

(Is there a template for these? I am entirely making this up.^^)

I'd like to propose stabilizing the raw_ref_macros feature. This feature guard two macros, core::ptr::raw_const! and core::ptr::raw_mut!. Both of these macros take path expressions and their effect is to create a raw pointer as described in RFC 2582.

This exposes a new primitive language ability: creating a raw pointer to something without going through an intermediate reference. This operation has been talked about in the Rust community for at least as long as I am around (I recall @arielb1 suggesting something like it). Example use cases that require such an operation are a general offset_of! macro, and creating pointers to unaligned fields of a packed struct. In particular, stabilizing this feature one way or another is crucial to unblock progress on one of the oldest open soundness bugs, #27060.

The aforementioned RFC proposes a new primitive syntax for these macros. However, we are not yet ready to commit to a stable syntax for these operations -- but we still would like to expose this ability to stable code. Following precedent like the try! macro, we thus propose to stabilize this feature through macros first, which is what the raw_ref_macros feature does.

Existing users

The raw_ref operation (whether through the syntax or the macro) is already seeing some use in-tree, e.g. in #73845 and #73971. Out-of-tree, Gilnaa/memoffset#43 ports the popular memoffset crate to use this operation.

An earlier crater experiment found around 50 crates that created references to unaligned fields of a packed struct. Some of those can probably be fixed by making copies instead of creating references (a common issue when using such fields in println! or comparison operations), but other likely truly need a pointer to that field, which currently cannot be created in a UB-free way.

Implementation history

• Add a raw "address of" operator #64588 added the primitive operation and syntax.
• add raw_ref macros #72279 added the macros.

Potential blockers/issues

• pub macro defined in submodule is shown at the wrong path #74355: rustdoc currently does not render pub macro macros correctly.

[nikomatsakis]

@RalfJung there is no template I'm aware of, I've been meaning to make one for some time

[nikomatsakis]

@rfcbot fcp merge

Following @RalfJung's excellent report, I propose that we stabilize the raw_const and raw_mut macros.