Rename std::ptr::Shared to NonNull and stabilize it #46952

SimonSapin · 2017-12-22T18:56:41Z

This implements the changes proposed at #27730 (comment):

Rename Shared<T> to NonNull<T> and stabilize it. (Being in the ptr module is enough to say that it’s a pointer. I’m not very attached to this specific name though.)

Rename Box<T> methods ~~from_unique~~/into_unique to ~~from_nonnull~~/into_nonnull (or whatever names are deemed appropriate), replace Unique<T> with NonNull<T> in their signatures, and stabilize them.

Replace Unique<T> with NonNull<T> in the signatures of methods of the Alloc trait.
Mark Unique “permanently-unstable” by replacing remaining occurrences of #[unstable(feature = "unique", issue = "27730")] with:
#[unstable(feature = "ptr_internals", issue = "0", reason = "\
    use NonNull instead and consider PhantomData<T> (if you also use #[may_dangle]), \
    Send, and/or Sync")]
(Maybe the reason string is only useful on the struct definition.) Ideally it would be made private to some crate instead, but it needs to be used in both liballoc and libstd.
(Leave NonZero and Zeroable unstable for now, and subject to future bikeshedding.)

rust-highfive · 2017-12-22T18:56:47Z

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @KodrAus (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

SimonSapin · 2017-12-22T18:57:56Z

That proposal so far has got a couple thumbs up and no negative comment or reaction. Maybe @rust-lang/libs can discuss and do a FCP in this thread?

leoyvens · 2017-12-22T19:14:24Z

Bikeshed: nonnull is an eyesore.

SimonSapin · 2017-12-22T19:17:50Z

@leodasvacas What’s your preferred shed color?

By your use of lower case I assume you mean in the Box methods. I’m very open to renaming them, do you have a suggestions? Ideally these might replace from_raw and into_raw, but those are already stable with *mut T.

leoyvens · 2017-12-22T19:22:24Z

Sorry for being unclear, I just prefer non_null over nonnull in method names that's all.

SimonSapin · 2017-12-22T19:25:20Z

Ok. So the methods would be Box::from_non_null_raw(…) and Box::into_non_null_raw(…). I don’t have a strong opinion either way, let’s see what other people think.

scottmcm · 2017-12-22T19:32:59Z

🚲🏡: since it's NonNull (not Nonnull), non_null makes sense over nonnull.

CC rust-lang/rust#46952

SimonSapin · 2017-12-22T22:48:21Z

I’ve pushed a commit to rename *_nonnull_raw to *_non_null_raw. Note however that there is precedent in the name of the core::nonzero module.

ExpHP · 2017-12-23T18:56:04Z

But core::nonzero is not stable, is it?

That said, riding in the 🚲 lane, non_zero certainly seems awkward. If I may suggest:

NotNull instead of NonNull.
Embrace "nonzero" as a single word.

use ::std::ptr::NotNull;
use ::core::nonzero::Nonzero;

fn foo() {
    let raw = NotNull::new(&0).unwrap();
    let _ = Box::from_not_null_raw(raw);
}

or leaning the other way, we could have ::std::ptr::Nonnull, but something about it just looks wrong to me...

SimonSapin · 2017-12-26T11:09:20Z

Besides naming, this is also a good time to reconsider whether Box::from_non_null_raw and Box::into_non_null_raw should exist in the first place.

I added into_non_null_raw in order to remove a few unsafe blocks in rc, arc, and linked_list. They use Box to allocate but then only keep a NonNull<T> pointer. Without this function, they (and other users doing similar things) would need unsafe to assert that the result of Box::into_raw() is not null.

So I think there's value in keeping this conversion in some form. It could be an impl of the From trait, but we generally avoid methods (as opposed to associated functions) on generic smart pointers as these could shadow methods of the contained type.

Box::from_non_zero_raw however I think we can remove. I added it at the same time, for symmetry, but it's not used at all in the tree. It can be replaced with Box::from_raw(some_non_null.get_mut()), both versions of this are unsafe anyway.

kennytm · 2017-12-27T15:22:20Z

src/libcore/ptr.rs

@@ -2331,8 +2331,9 @@ impl<T: ?Sized> PartialOrd for *mut T {
 /// Unlike `*mut T`, `Unique<T>` is covariant over `T`. This should always be correct
 /// for any type which upholds Unique's aliasing requirements.
 #[allow(missing_debug_implementations)]


Could you impl Debug for NonNull (superseding #46792)?

goodmanjonathan · 2017-12-27T17:22:50Z

src/libcore/ptr.rs

 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 fmt::Pointer::fmt(&self.as_ptr(), f)
 }
 }

-#[unstable(feature = "shared", issue = "27730")]
-impl<T: ?Sized> From<Unique<T>> for Shared<T> {
+#[stable(feature = "nonnull", since = "1.24.0")]


Shouldn't this be #[unstable(feature = "unique")]?

Maybe. Even if this impl is usable, it can’t be used if you can’t get a Unique<T> value in the first place on stable Rust. And anyway, IIRC stability attributes don’t work on impl blocks at the moment. (They’re insta-stable if the relevant traits and types are stable.)

Right, I was just afraid it might have other effects (e.g. like showing up in rustdoc). If not, I'm fine either way.

Unstable impls are visible in rustdoc too: https://doc.rust-lang.org/std/ptr/struct.Shared.html#impl-From%3CUnique%3CT%3E%3E

Alright, then.

SimonSapin · 2017-12-27T22:00:41Z

Rebased on top of Implement Debug for ptr::Shared and ptr::Unique. #46792
Removed Box::from_non_null_raw (can be replaced with Box::from_raw(x.get_mut()))
Renamed Box::into_non_null_raw to Box::into_raw_non_null

SimonSapin · 2017-12-29T16:09:23Z

It could be an impl of the From trait, but we generally avoid methods (as opposed to associated functions) on generic smart pointers as these could shadow methods of the contained type.

However we already have impl<'a, T: ?Sized> From<&'a T> for NonNull<T> and impl<'a, T: ?Sized> From<&'a mut T> for NonNull<T> which (indirectly) add an .into() method on &T and &mut T. So maybe it’s not such a problem in practice?

SimonSapin · 2017-12-29T16:19:26Z

Pushed another commit (that we can remove from the PR if it turns out problematic) that replaces Box::into_raw_non_null with an impl of the Into trait. (Not From because coherence.)

kennytm · 2017-12-29T16:27:53Z

I don't think it's a good idea to reintroduce an Into impl, esp. when the corresponding From can't exist...

rust-lang#47336

SimonSapin · 2018-01-20T10:09:49Z

Checking "basic.js" ... OK
Checking "enum-option.js" ... OK
Checking "fn-forget.js" ... OK
Checking "from_u.js" ... FAILED
==> Result not found in 'others': '{"path":"std::boxed::Box","name":"from_unique"}'
Checking "macro-print.js" ... OK
Checking "string-from_ut.js" ... OK
Checking "struct-vec.js" ... OK
command did not execute successfully: "C:\\Program Files (x86)\\nodejs\\node" "src/tools/rustdoc-js/tester.js" "x86_64-pc-windows-msvc"
expected success, got: exit code: 1

Sigh. This PR changes the expected result of an unrelated test (rustdoc seach results) that was added after the PR was created. Should be fixed now:

diff --git a/src/test/rustdoc-js/from_u.js b/src/test/rustdoc-js/from_u.js
index 920620a9ae..0296788f7a 100644
--- a/src/test/rustdoc-js/from_u.js
+++ b/src/test/rustdoc-js/from_u.js
@@ -15,7 +15,6 @@ const EXPECTED = {
         { 'path': 'std::char', 'name': 'from_u32' },
         { 'path': 'std::str', 'name': 'from_utf8' },
         { 'path': 'std::string::String', 'name': 'from_utf8' },
-        { 'path': 'std::boxed::Box', 'name': 'from_unique' },
         { 'path': 'std::i32', 'name': 'from_unsigned' },
         { 'path': 'std::i128', 'name': 'from_unsigned' },
     ],

eddyb · 2018-01-20T10:16:08Z

@bors r=alexcrichton

bors · 2018-01-20T10:16:09Z

📌 Commit 602a445 has been approved by alexcrichton

bors · 2018-01-20T12:28:20Z

⌛ Testing commit 602a445 with merge bdda8d6...

Rename std::ptr::Shared to NonNull and stabilize it This implements the changes proposed at #27730 (comment): > * Rename `Shared<T>` to `NonNull<T>` and stabilize it. (Being in the `ptr` module is enough to say that it’s a pointer. I’m not very attached to this specific name though.) > * Rename `Box<T>` methods ~~`from_unique`~~/`into_unique` to ~~`from_nonnull`~~/`into_nonnull` (or whatever names are deemed appropriate), replace `Unique<T>` with `NonNull<T>` in their signatures, and stabilize them. > * Replace `Unique<T>` with `NonNull<T>` in the signatures of methods of the `Alloc` trait. > * Mark `Unique` “permanently-unstable” by replacing remaining occurrences of `#[unstable(feature = "unique", issue = "27730")]` with: > > ```rust > #[unstable(feature = "ptr_internals", issue = "0", reason = "\ > use NonNull instead and consider PhantomData<T> (if you also use #[may_dangle]), \ > Send, and/or Sync")] > ``` > > (Maybe the `reason` string is only useful on the struct definition.) Ideally it would be made private to some crate instead, but it needs to be used in both liballoc and libstd. > * (Leave `NonZero` and `Zeroable` unstable for now, and subject to future bikeshedding.)

bors · 2018-01-20T15:06:36Z

☀️ Test successful - status-appveyor, status-travis
Approved by: alexcrichton
Pushing bdda8d6 to master...

Gankra · 2018-01-20T15:10:31Z

\o/ you did it!

joshlf · 2018-01-21T03:00:10Z

Stop me if I should bring this up in a new issue, but how do folks feel about adding a conversion from NonNull<T> to NonNull<U>? It wouldn't add any extra unsafety because you can already do NonNull::new(x.as_ptr() as *mut U).unwrap(), and would basically be a cleaner way of writing that.

SimonSapin · 2018-01-21T07:34:43Z

@joshlf It should probably be a new issue (or a PR ;)) but I’ve been thinking the same when considering whether every *mut u8 in return types in the Alloc trait should be NonNull<u8> instead. For now though I think the need is less pressing as long as there are few APIs that return NonNull<_>: if you create it from a raw pointer anyway, you can cast with as beforehand.

joshlf · 2018-01-21T09:08:15Z

Would've submitted a PR, but I see you've beaten me to it :)

…

On Jan 20, 2018 11:34 PM, "Simon Sapin" ***@***.***> wrote: @joshlf <https://github.com/joshlf> It should probably be a new issue (or a PR ;)) but I’ve been thinking the same when considering whether every *mut u8 in return types in the Alloc trait should be NonNull<u8> instead. So for though I think the need is less pressing as long as there are few APIs that return NonNull<_>: if you create it from a raw pointer anyway, you can cast with as beforehand. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#46952 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA_2L_mZdcvSPvPHjYXaz1V6BSo1rguWks5tMuiagaJpZM4RLVAQ> .

SimonSapin · 2018-01-21T09:33:55Z

Oops, I forgot to comment here about it. Yeah, since I was making other changes… :)

… change more in the future due to rust-lang/rust#46952

Add some APIs to ptr::NonNull and fix `since` attributes This is a follow-up to its stabilization in rust-lang#46952. Tracking issue: rust-lang#27730. * These trait impls are insta-stable: `Hash`, `PartialEq`, `Eq`, `PartialOrd` and `Ord`. * The new `cast<U>() -> NonNull<U>` method is `#[unstable]`. It was proposed in rust-lang#46952 (comment).

@withoutboats

Add Into<NonNull<T>> impls for Arc<T>/Rc<T> /cc @withoutboats who mentioned to me this might be worth adding to the standard library, in withoutboats/smart#4 /cc @kennytm who last year didn't love the idea of having an Into<NonNull<T>> for Box<T>, in #46952

rust-highfive assigned KodrAus Dec 22, 2017

SimonSapin mentioned this pull request Dec 22, 2017

Tracking issue for NonZero/Unique/Shared stabilization #27730

Closed

SimonSapin force-pushed the nonnull branch from 92b6403 to ed13cc0 Compare December 22, 2017 19:00

kennytm added S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). T-libs-api Relevant to the library API team, which will review and decide on the PR/issue. labels Dec 22, 2017

joshlf mentioned this pull request Dec 22, 2017

Switch object-alloc and dependents to NonNull raw pointers ezrosent/allocators-rs#140

Closed

SimonSapin added a commit to SimonSapin/nomicon that referenced this pull request Dec 22, 2017

The unique feature is renamed ptr_internals

2b35eba

CC rust-lang/rust#46952

SimonSapin mentioned this pull request Dec 22, 2017

The unique feature is renamed ptr_internals rust-lang/nomicon#48

Merged

SimonSapin force-pushed the nonnull branch from ed13cc0 to 5245a61 Compare December 22, 2017 20:13

SimonSapin mentioned this pull request Dec 22, 2017

The unique feature is renamed ptr_internals rust-lang/nomicon#49

Merged

SimonSapin force-pushed the nonnull branch from 5245a61 to 06b7945 Compare December 22, 2017 20:56

kennytm mentioned this pull request Dec 27, 2017

Implement Debug for ptr::Shared and ptr::Unique. #46792

Closed

kennytm reviewed Dec 27, 2017

View reviewed changes

goodmanjonathan reviewed Dec 27, 2017

View reviewed changes

SimonSapin force-pushed the nonnull branch from 588ea9e to f91240e Compare December 27, 2017 21:59

SimonSapin added 4 commits January 20, 2018 11:09

Preserve formatting options in Debug for NonNull/Unique

a1db237

Revert Box::into_raw_non_null to unstable

5aeeaff

Rename NonNull::empty to dangling.

76b686f

Assign its own tracking issue to Box::into_raw_non_null

602a445

rust-lang#47336

SimonSapin force-pushed the nonnull branch from 2cf5c6a to 602a445 Compare January 20, 2018 10:09

bors merged commit 602a445 into rust-lang:master Jan 20, 2018

bors mentioned this pull request Jan 20, 2018

[proof of concept] give String support for CoW wrapping of literals #46993

Closed

bluss added the relnotes Marks issues that should be documented in the release notes of the next release. label Jan 20, 2018

SimonSapin deleted the nonnull branch January 20, 2018 15:50

hawkw mentioned this pull request Jan 20, 2018

intruder_alarm stability sos-os/alarm#12

Open

SimonSapin mentioned this pull request Jan 21, 2018

Add some APIs to ptr::NonNull and fix since attributes #47631

Merged

rozbb added a commit to Aatch/ramp that referenced this pull request Jan 22, 2018

Change feature(unique) to feature(ptr_internals); will likely have to…

f8ecd1c

… change more in the future due to rust-lang/rust#46952

declanvk mentioned this pull request Feb 3, 2018

Crate failed to build rust-lang/docs.rs#23

Closed

Bobo1239 mentioned this pull request Aug 13, 2018

Remove unique feature which doesn't exist anymore rust-lang/nomicon#84

Merged

dwijnand mentioned this pull request Dec 19, 2018

Add Into<NonNull<T>> impls for Box<T>/Arc<T>/Rc<T> #56998

Closed

RalfJung mentioned this pull request Apr 25, 2020

Document unsafety in core::ptr #71507

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rename std::ptr::Shared to NonNull and stabilize it #46952

Rename std::ptr::Shared to NonNull and stabilize it #46952

SimonSapin commented Dec 22, 2017 •

edited

Loading

rust-highfive commented Dec 22, 2017

SimonSapin commented Dec 22, 2017

leoyvens commented Dec 22, 2017

SimonSapin commented Dec 22, 2017

leoyvens commented Dec 22, 2017

SimonSapin commented Dec 22, 2017

scottmcm commented Dec 22, 2017

SimonSapin commented Dec 22, 2017

ExpHP commented Dec 23, 2017 •

edited

Loading

SimonSapin commented Dec 26, 2017 •

edited

Loading

kennytm Dec 27, 2017

goodmanjonathan Dec 27, 2017

SimonSapin Dec 27, 2017

goodmanjonathan Dec 27, 2017

SimonSapin Dec 27, 2017

goodmanjonathan Dec 27, 2017

SimonSapin commented Dec 27, 2017

SimonSapin commented Dec 29, 2017

SimonSapin commented Dec 29, 2017

kennytm commented Dec 29, 2017

SimonSapin commented Jan 20, 2018

eddyb commented Jan 20, 2018

bors commented Jan 20, 2018

bors commented Jan 20, 2018

bors commented Jan 20, 2018

Gankra commented Jan 20, 2018

joshlf commented Jan 21, 2018

SimonSapin commented Jan 21, 2018 •

edited

Loading

joshlf commented Jan 21, 2018 via email

SimonSapin commented Jan 21, 2018

Rename std::ptr::Shared to NonNull and stabilize it #46952

Rename std::ptr::Shared to NonNull and stabilize it #46952

Conversation

SimonSapin commented Dec 22, 2017 • edited Loading

rust-highfive commented Dec 22, 2017

SimonSapin commented Dec 22, 2017

leoyvens commented Dec 22, 2017

SimonSapin commented Dec 22, 2017

leoyvens commented Dec 22, 2017

SimonSapin commented Dec 22, 2017

scottmcm commented Dec 22, 2017

SimonSapin commented Dec 22, 2017

ExpHP commented Dec 23, 2017 • edited Loading

SimonSapin commented Dec 26, 2017 • edited Loading

kennytm Dec 27, 2017

Choose a reason for hiding this comment

goodmanjonathan Dec 27, 2017

Choose a reason for hiding this comment

SimonSapin Dec 27, 2017

Choose a reason for hiding this comment

goodmanjonathan Dec 27, 2017

Choose a reason for hiding this comment

SimonSapin Dec 27, 2017

Choose a reason for hiding this comment

goodmanjonathan Dec 27, 2017

Choose a reason for hiding this comment

SimonSapin commented Dec 27, 2017

SimonSapin commented Dec 29, 2017

SimonSapin commented Dec 29, 2017

kennytm commented Dec 29, 2017

SimonSapin commented Jan 20, 2018

eddyb commented Jan 20, 2018

bors commented Jan 20, 2018

bors commented Jan 20, 2018

bors commented Jan 20, 2018

Gankra commented Jan 20, 2018

joshlf commented Jan 21, 2018

SimonSapin commented Jan 21, 2018 • edited Loading

joshlf commented Jan 21, 2018 via email

SimonSapin commented Jan 21, 2018

SimonSapin commented Dec 22, 2017 •

edited

Loading

ExpHP commented Dec 23, 2017 •

edited

Loading

SimonSapin commented Dec 26, 2017 •

edited

Loading

SimonSapin commented Jan 21, 2018 •

edited

Loading