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

[SimonSapin]

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]

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]

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?

[leodasvacas]

Bikeshed: nonnull is an eyesore.

[SimonSapin]

@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.

[leodasvacas]

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

[SimonSapin]

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]

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

[SimonSapin]

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]

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]

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]

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

[goodmanjonathan]

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

[SimonSapin]

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.)

[goodmanjonathan]

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

[SimonSapin]

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

[goodmanjonathan]

Alright, then.

[SimonSapin]

• Rebased on top of #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]

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]

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]

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

[SimonSapin]

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]

@bors r=alexcrichton

[bors]

📌 Commit 602a445 has been approved by alexcrichton

[bors]

⌛️ Testing commit 602a445 with merge bdda8d6...

[bors]

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

[Gankro]

\o/ you did it!

[joshlf]

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]

@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]

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]

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