Document NonNull layout guarantees by 0xEgao · Pull Request #158325 · rust-lang/rust

0xEgao · 2026-06-23T18:51:11Z

View all comments

As discussed here
Fixes #157741

This updates the NonNull layout docs to match the structure and wording used by NonZero.

adds the missing NonNull<T> layout and validity wording, and documents that Option<NonNull<T>> is compatible with *mut T, including in FFI.

r? @RalfJung

rustbot · 2026-06-23T18:51:16Z

RalfJung is not on the review rotation at the moment.
They may take a while to respond.

rustbot · 2026-06-23T18:51:17Z

Thanks for the pull request, and welcome! The Rust Project is excited to review your changes, and you should hear from @RalfJung (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

@rustbot author: the review is finished, PR author should check the comments and take action accordingly
@rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

0xEgao · 2026-06-30T14:15:48Z

@rustbot review

RalfJung · 2026-06-30T14:53:47Z

No worries, this is in my queue. The queue is just particularly long right now since I was traveling for 2 weeks and came back to around 300 emails in my inbox. It takes a while to go through all that.

RalfJung · 2026-07-02T12:11:28Z

Cc @rust-lang/opsem -- but I think there's nothing new here, we already document the same ABI compatibility in the fn ptr section. Makes sense to me to also have it on the type, like we do for NonZero*.

Thanks @0xEgao!
@bors r+ rollup

rust-bors · 2026-07-02T12:11:31Z

📌 Commit 8f66cfd has been approved by RalfJung

It is now in the queue for this repository.

🌲 The tree is currently closed for pull requests below priority 1000. This pull request will be tested once the tree is reopened.

RalfJung · 2026-07-02T12:14:33Z

@bors r-
Hm, actually, I think we didn't spell out this layout anywhere before. Though giving an ABI guarantee without a layout guarantee makes very little sense. But still, let's go the official route.
@rfcbot fcp merge opsem

Cc @rust-lang/lang in case you have an opinion/concern

rust-rfcbot · 2026-07-02T12:14:35Z

@RalfJung has proposed to merge this. The next step is review by the rest of the tagged team members:

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

rust-bors · 2026-07-02T12:14:37Z

This pull request was unapproved.

View changes since this unapproval

scottmcm · 2026-07-02T16:50:08Z

Yup, seems entirely non-controversial 👍

joshlf · 2026-07-02T18:19:59Z

+///
+/// `NonNull<T>` is guaranteed to have the same layout and bit validity as `*mut T`
+/// with the exception that a null pointer is invalid.
+/// `Option<NonNull<T>>` is guaranteed to be compatible with `*mut T`, including in


Suggested change

/// `Option<NonNull<T>>` is guaranteed to be compatible with `*mut T`, including in

/// `Option<NonNull<T>>` is guaranteed to be ABI-compatible with `*mut T`, including in

Does the word "compatible" on its own have a well-defined meaning?

View changes since the review

I don't know, but if we change this we should also change it for NonZero*.

Yeah i think it's better to change that in both cases

scottmcm · 2026-07-02T18:35:32Z

Pondering: when we're talking ABI-compatibility in signatures, how do we square LLVM attributes like nonnull (or range on NonZero<_>) with that? If I write a signature for it with a restriction like that, does it affect others who declare the extern differently?

RalfJung · 2026-07-02T18:47:43Z

I think you're thinking about #46188 ?
There's nothing new in the regard in this PR though (the NonZero* types would have the same problems, if there are any), so if you think there's a problem here, it's probably better to create a new thread/issue somewhere else.

rust-rfcbot · 2026-07-02T23:42:34Z

🔔 This is now entering its final comment period, as per the review above. 🔔

RalfJung

r=me on the wording, we just need to wait until FCP passes. :)

View changes since this review

rust-rfcbot · 2026-07-12T23:52:40Z

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

RalfJung · 2026-07-13T06:47:25Z

@bors r+ rollup

Thanks all :)

rust-bors · 2026-07-13T06:47:28Z

📋 This PR cannot be approved because it currently has the following label: S-waiting-on-fcp.

RalfJung · 2026-07-13T06:48:27Z

@bors r+ rollup

rust-bors · 2026-07-13T06:48:31Z

📌 Commit 74c99d9 has been approved by RalfJung

It is now in the queue for this repository.

@RalfJung

Document NonNull layout guarantees As discussed [here](rust-lang#157982 (comment)) Fixes rust-lang#157741 This updates the `NonNull` layout docs to match the structure and wording used by `NonZero`. - adds the missing `NonNull<T>` layout and validity wording, and documents that `Option<NonNull<T>>` is compatible with `*mut T`, including in FFI. r? @RalfJung

Rollup of 11 pull requests Successful merges: - #159210 (`rust-analyzer` subtree update) - #158655 (Fix coroutine MIR saved local remapping) - #159205 (bootstrap: Replace `ShouldRun::crates` with `crate_or_deps_filtered`) - #159208 (Fix `attr_on_non_tail_expr` typo) - #157524 (Fix relative paths in private import suggestions) - #158325 (Document NonNull layout guarantees) - #158882 (enable `do_not_recommend` attr for method call errors in current solver) - #158982 (Pretty-print MIR user types too.) - #159069 (Add codegen test for constant returns after local use) - #159163 (rustc_target: Add acquire-release to implied features of v8) - #159201 (borrowck: Represent 'best blame constraint' as index into `Vec<OutlivesConstraint>`)

@RalfJung

Rollup merge of #158325 - 0xEgao:docs-non-null, r=RalfJung Document NonNull layout guarantees As discussed [here](#157982 (comment)) Fixes #157741 This updates the `NonNull` layout docs to match the structure and wording used by `NonZero`. - adds the missing `NonNull<T>` layout and validity wording, and documents that `Option<NonNull<T>>` is compatible with `*mut T`, including in FFI. r? @RalfJung

rustbot assigned RalfJung Jun 23, 2026

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Jun 23, 2026

rust-bors Bot added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 2, 2026

rust-bors Bot added the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Jul 2, 2026

rust-rfcbot added the proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. label Jul 2, 2026

rust-bors Bot removed the S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. label Jul 2, 2026

rust-rfcbot added the disposition-merge This issue / PR is in PFCP or FCP with a disposition to merge it. label Jul 2, 2026

RalfJung added S-waiting-on-t-opsem Status: Awaiting decision from T-opsem and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jul 2, 2026

joshlf reviewed Jul 2, 2026

View reviewed changes

rust-rfcbot added the final-comment-period In the final comment period and will be merged soon unless new substantive objections are raised. label Jul 2, 2026

rust-rfcbot removed the proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. label Jul 2, 2026

Document NonNull layout guarantees

74c99d9

0xEgao force-pushed the docs-non-null branch from 8f66cfd to 74c99d9 Compare July 6, 2026 07:41

0xEgao requested a review from RalfJung July 6, 2026 07:42

0xEgao requested a review from joshlf July 6, 2026 07:42

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jul 6, 2026

RalfJung added S-waiting-on-fcp Status: PR is in FCP and is awaiting for FCP to complete. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. S-waiting-on-t-opsem Status: Awaiting decision from T-opsem labels Jul 8, 2026

RalfJung approved these changes Jul 8, 2026

View reviewed changes

rust-rfcbot added finished-final-comment-period The final comment period is finished for this PR / Issue. and removed final-comment-period In the final comment period and will be merged soon unless new substantive objections are raised. labels Jul 12, 2026

rust-rfcbot added the to-announce Announce this issue on triage meeting label Jul 12, 2026

rustbot mentioned this pull request Jul 12, 2026

Tracking issue for release notes of #158325: Document NonNull layout guarantees #159198

Closed

RalfJung removed the S-waiting-on-fcp Status: PR is in FCP and is awaiting for FCP to complete. label Jul 13, 2026

rust-bors Bot added the S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. label Jul 13, 2026

This was referenced Jul 13, 2026

Rollup of 7 pull requests #159212

Closed

Rollup of 11 pull requests #159213

Merged

rust-bors Bot merged commit 063c692 into rust-lang:main Jul 13, 2026
13 checks passed

rustbot added this to the 1.99.0 milestone Jul 13, 2026

	/// `Option<NonNull<T>>` is guaranteed to be compatible with `*mut T`, including in
	/// `Option<NonNull<T>>` is guaranteed to be ABI-compatible with `*mut T`, including in

Uh oh!

Uh oh!

Conversation

0xEgao commented Jun 23, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Jun 23, 2026

Uh oh!

rustbot commented Jun 23, 2026

Uh oh!

0xEgao commented Jun 30, 2026

Uh oh!

RalfJung commented Jun 30, 2026

Uh oh!

RalfJung commented Jul 2, 2026

Uh oh!

rust-bors Bot commented Jul 2, 2026

Uh oh!

RalfJung commented Jul 2, 2026

Uh oh!

rust-rfcbot commented Jul 2, 2026 • edited by saethlin Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rust-bors Bot commented Jul 2, 2026

Uh oh!

scottmcm commented Jul 2, 2026

Uh oh!

joshlf Jul 2, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RalfJung Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

0xEgao Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

scottmcm commented Jul 2, 2026

Uh oh!

RalfJung commented Jul 2, 2026

Uh oh!

rust-rfcbot commented Jul 2, 2026

Uh oh!

RalfJung left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rust-rfcbot commented Jul 12, 2026

Uh oh!

RalfJung commented Jul 13, 2026

Uh oh!

rust-bors Bot commented Jul 13, 2026

Uh oh!

RalfJung commented Jul 13, 2026

Uh oh!

rust-bors Bot commented Jul 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

0xEgao commented Jun 23, 2026 •

edited by rustbot

Loading

rust-rfcbot commented Jul 2, 2026 •

edited by saethlin

Loading

joshlf Jul 2, 2026 •

edited by rustbot

Loading

RalfJung left a comment •

edited by rustbot

Loading