Empowering everyone to build reliable and efficient software.
Go to file
Trevor Gross f27a9b15d3
Rollup merge of - RalfJung:raw_ref_op, r=jieyouxu
Stabilize `raw_ref_op` (RFC 2582)

This stabilizes the syntax `&raw const $expr` and `&raw mut $expr`. It has existed unstably for ~4 years now, and has been exposed on stable via the `addr_of` and `addr_of_mut` macros since Rust 1.51 (released more than 3 years ago). I think it has become clear that these operations are here to stay. So it is about time we give them proper primitive syntax. This has two advantages over the macro:

- Being macros, `addr_of`/`addr_of_mut` could in theory do arbitrary magic with the expression on which they work. The only "magic" they actually do is using the argument as a place expression rather than as a value expression. Place expressions are already a subtle topic and poorly understood by many programmers; having this hidden behind a macro using unstable language features makes this even worse. Conversely, people do have an idea of what happens below `&`/`&mut`, so we can make the subtle topic a lot more approachable by connecting to existing intuition.
- The name `addr_of` is quite unfortunate from today's perspective, given that we have accepted provenance as a reality, which means that a pointer is *not* just an address. Strict provenance has a method, `addr`, which extracts the address of a pointer; using the term `addr` in two different ways is quite unfortunate. That's why this PR soft-deprecates `addr_of` -- we will wait a long time before actually showing any warning here, but we should start telling people that the "addr" part of this name is somewhat misleading, and `&raw` avoids that potential confusion.

In summary, this syntax improves developers' ability to conceptualize the operational semantics of Rust, while making a fundamental operation frequently used in unsafe code feel properly built in.

Possible questions to consider, based on the RFC and [this](https://github.com/rust-lang/rust/issues/64490#issuecomment-1163802912) great summary by `@CAD97:`

- Some questions are entirely about the semantics. The semantics are the same as with the macros so I don't think this should have any impact on this syntax PR. Still, for completeness' sake:
  - Should `&raw const *mut_ref` give a read-only pointer?
    - Tracked at: https://github.com/rust-lang/unsafe-code-guidelines/issues/257
    - I think ideally the answer is "no". Stacked Borrows says that pointer is read-only, but Tree Borrows says it is mutable.
  - What exactly does `&raw const (*ptr).field` require? Answered in [the reference](https://doc.rust-lang.org/nightly/reference/behavior-considered-undefined.html): the arithmetic to compute the field offset follows the rules of `ptr::offset`, making it UB if it goes out-of-bounds. Making this a safe operation (using `wrapping_offset` rules) is considered too much of a loss for alias analysis.
- Choose a different syntax? I don't want to re-litigate the RFC. The only credible alternative that has been proposed is `&raw $place` instead of `&raw const $place`, which (IIUC) could be achieved by making `raw` a contextual keyword in a new edition. The type is named `*const T`, so the explicit `const` is consistent in that regard. `&raw expr` lacks the explicit indication of immutability. However, `&raw const expr` is quite a but longer than `addr_of!(expr)`.
- Shouldn't we have a completely new, better raw pointer type instead? Yes we all want to see that happen -- but I don't think we should block stabilization on that, given that such a nicer type is not on the horizon currently and given the issues with `addr_of!` mentioned above. (If we keep the `&raw $place` syntax free for this, we could use it in the future for that new type.)
- What about the lint the RFC talked about? It hasn't been implemented yet.  Given that the problematic code is UB with or without this stabilization, I don't think the lack of the lint should block stabilization.
  - I created an issue to track adding it: https://github.com/rust-lang/rust/issues/127724
- Other points from the "future possibilites of the RFC
  - "Syntactic sugar" extension: this has not been implemented. I'd argue this is too confusing, we should stick to what the RFC suggested and if we want to do anything about such expressions, add the lint.
  - Encouraging / requiring `&raw` in situations where references are often/definitely incorrect: this has been / is being implemented. On packed fields this already is a hard error, and for `static mut` a lint suggesting raw pointers is being rolled out.
  - Lowering of casts: this has been implemented. (It's also an invisible implementation detail.)
  - `offsetof` woes: we now have native `offset_of` so this is not relevant any more.

To be done before landing:

- [x] Suppress `unused_parens` lint around `&raw {const|mut}` expressions
  - See bottom of https://github.com/rust-lang/rust/pull/127679#issuecomment-2264073752 for rationale
  - Implementation: https://github.com/rust-lang/rust/pull/128782
- [ ] Update the Reference.
  - https://github.com/rust-lang/reference/pull/1567

Fixes https://github.com/rust-lang/rust/issues/64490

cc `@rust-lang/lang` `@rust-lang/opsem`

try-job: x86_64-msvc
try-job: test-various
try-job: dist-various-1
try-job: armhf-gnu
try-job: aarch64-apple
2024-08-18 23:41:46 -05:00
.github Fix dependencies cron job 2024-08-14 09:57:14 -07:00
compiler Rollup merge of - RalfJung:raw_ref_op, r=jieyouxu 2024-08-18 23:41:46 -05:00
library soft-deprecate the addr_of macros 2024-08-18 19:46:53 +02:00
LICENSES Include REUSE.toml in REUSE.toml. 2024-07-22 09:44:18 +01:00
src Rollup merge of - RalfJung:raw_ref_op, r=jieyouxu 2024-08-18 23:41:46 -05:00
tests Rollup merge of - RalfJung:raw_ref_op, r=jieyouxu 2024-08-18 23:41:46 -05:00
.clang-format
.editorconfig
.git-blame-ignore-revs Ignore use declaration reformatting in .git-blame-ignore-revs. 2024-08-01 14:33:17 +10:00
.gitattributes
.gitignore gitignore: Add Zed and Helix editors 2024-08-09 21:26:27 +01:00
.gitmodules Update to LLVM 19 2024-07-30 10:22:48 +02:00
.ignore
.mailmap trans her gender 2024-07-27 23:36:23 +00:00
Cargo.lock Rollup merge of - ChrisDenton:comdat, r=jieyouxu 2024-08-18 14:55:22 +08:00
Cargo.toml Use -D warnings instead of deny-warnings feature. 2024-08-06 10:46:39 -04:00
CODE_OF_CONDUCT.md
config.example.toml Enable zstd for debug compression. 2024-08-09 05:55:23 -07:00
configure
CONTRIBUTING.md
COPYRIGHT
INSTALL.md Rollup merge of - onur-ozkan:use-bootstrap-instead-of-rustbuild, r=Mark-Simulacrum 2024-07-13 20:19:45 -07:00
LICENSE-APACHE
LICENSE-MIT
README.md
RELEASES.md Fix 1.80.0 version in RELEASES.md 2024-07-25 16:57:57 +02:00
REUSE.toml REUSE.toml: Copyright text isn't parsed as Markdown. 2024-08-06 11:04:55 +01:00
rust-bors.toml
rustfmt.toml Auto merge of - Mark-Simulacrum:bump-bootstrap, r=albertlarsan68 2024-07-30 17:49:08 +00:00
triagebot.toml Remove JohnTitor from review rotation 2024-08-17 17:34:52 -07:00
x
x.ps1
x.py

This is the main source code repository for Rust. It contains the compiler, standard library, and documentation.

Why Rust?

  • Performance: Fast and memory-efficient, suitable for critical services, embedded devices, and easily integrate with other languages.

  • Reliability: Our rich type system and ownership model ensure memory and thread safety, reducing bugs at compile-time.

  • Productivity: Comprehensive documentation, a compiler committed to providing great diagnostics, and advanced tooling including package manager and build tool (Cargo), auto-formatter (rustfmt), linter (Clippy) and editor support (rust-analyzer).

Quick Start

Read "Installation" from The Book.

Installing from Source

If you really want to install from source (though this is not recommended), see INSTALL.md.

Getting Help

See https://www.rust-lang.org/community for a list of chat platforms and forums.

Contributing

See CONTRIBUTING.md.

License

Rust is primarily distributed under the terms of both the MIT license and the Apache License (Version 2.0), with portions covered by various BSD-like licenses.

See LICENSE-APACHE, LICENSE-MIT, and COPYRIGHT for details.

Trademark

The Rust Foundation owns and protects the Rust and Cargo trademarks and logos (the "Rust Trademarks").

If you want to use these names or brands, please read the media guide.

Third-party logos may be subject to third-party copyrights and trademarks. See Licenses for details.