Implement ptr_as_ref_unchecked #122492
Implement ptr_as_ref_unchecked #122492
Conversation
|
rustbot has assigned @workingjubilee. Use r? to explicitly pick a reviewer |
rustbot
added
S-waiting-on-review
|
Did not replace any ptr- |
| /// In particular, while this reference exists, the memory the pointer points to must | ||
| /// not get mutated (except inside `UnsafeCell`). |
There was a problem hiding this comment.
If I understand correctly it is still illegal to mutate &'a Inner if I use this to obtain &'a Inner directly, instead of &'a UnsafeCell<Inner>. It might be better to describe this as "except via pointers obtained by UnsafeCell::get and other functions on UnsafeCell." Again, I understand this has already been copied a zillion times and you didn't originate this.
| /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is | ||
| /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. |
There was a problem hiding this comment.
I realize this is copied from elsewhere but it has been copied so often with subtle changes of the context around it that by being a copy of a copy of a copy it reads fairly jarringly in this new case. I would prefer it was more explicit to explain that you, the caller of this unsafe fn, define the 'a lifetime by calling this (you may pass an explicit generic via turbofish, or it will be inferred). You are making a claim that you will uphold it for that long, and "arbitrarily chosen" makes it sound more... impersonal.
All of those requirements, except mutation (which is stated in this clause) are stated previously, so perhaps it would be better to move the non-mutation clause into its own bullet. Then it can simply say "all of the previous rules".
| /// Returns a shared reference to the value behind the pointer. | ||
| /// If the pointer may be null or the value may be uninitialized, [`as_uninit_ref`] must be used instead. | ||
| /// If the pointer may be null, but the value is known to have been initialized, [`as_ref`] must be used instead. | ||
| /// | ||
| /// For the mutable counterpart see [`as_mut_unchecked`]. | ||
| /// | ||
| /// [`as_ref`]: #method.as_ref | ||
| /// [`as_uninit_ref`]: #method.as_uninit_ref | ||
| /// [`as_mut_unchecked`]: #method.as_mut_unchecked | ||
| /// | ||
| /// # Safety | ||
| /// | ||
| /// When calling this method, you have to ensure that all of the following is true: | ||
| /// | ||
| /// * The pointer must be properly aligned. | ||
| /// | ||
| /// * It must be "dereferenceable" in the sense defined in [the module documentation]. | ||
| /// | ||
| /// * The pointer must point to an initialized instance of `T`. | ||
| /// | ||
| /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is | ||
| /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. | ||
| /// In particular, while this reference exists, the memory the pointer points to must | ||
| /// not get mutated (except inside `UnsafeCell`). | ||
| /// | ||
| /// This applies even if the result of this method is unused! | ||
| /// (The part about being initialized is not yet fully decided, but until | ||
| /// it is, the only safe approach is to ensure that they are indeed initialized.) | ||
| /// | ||
| /// [the module documentation]: crate::ptr#safety | ||
| /// | ||
| /// # Examples | ||
| /// | ||
| /// ``` | ||
| /// #![feature(ptr_as_ref_unchecked)] | ||
| /// let ptr: *mut u8 = &mut 10u8 as *mut u8; | ||
| /// | ||
| /// unsafe { | ||
| /// println!("We got back the value: {}!", ptr.as_ref_unchecked()); | ||
| /// } | ||
| /// ``` | ||
| // FIXME: mention it in the docs for `as_ref` and `as_uninit_ref` once stabilized. |
There was a problem hiding this comment.
My comments from before apply down the line here.
| /// ``` | ||
| // FIXME: mention it in the docs for `as_ref` and `as_uninit_ref` once stabilized. | ||
| #[unstable(feature = "ptr_as_ref_unchecked", issue = "122034")] | ||
| #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] |
There was a problem hiding this comment.
Are we sure we should be associating this with const-stability of this set of fn instead of just landing these as const stable when we land them? Can you make sure the two issues are crosslinked and mention that as an option?
| /// unsafe { | ||
| /// println!("We got back the value: {}!", ptr.as_ref_unchecked()); | ||
| /// } |
There was a problem hiding this comment.
A lot of doctests don't really test anything because they're no_run or they only have prints like this one. Perhaps this could test something simple like
assert!(10.eq(ptr.as_ref_unchecked()));| /// let ptr: *mut u32 = s.as_mut_ptr(); | ||
| /// let first_value = unsafe { ptr.as_mut_unchecked() }; | ||
| /// *first_value = 4; | ||
| /// # assert_eq!(s, [4, 2, 3]); |
There was a problem hiding this comment.
Why are we hiding the assert_eq! here?
There was a problem hiding this comment.
There was a problem hiding this comment.
ah, delicious italian food
| /// Returns a unique reference to the value behind the pointer. | ||
| /// If the pointer may be null or the value may be uninitialized, [`as_uninit_mut`] must be used instead. | ||
| /// If the pointer may be null, but the value is known to have been initialized, [`as_mut`] must be used instead. | ||
| /// | ||
| /// For the shared counterpart see [`as_ref_unchecked`]. | ||
| /// | ||
| /// [`as_mut`]: #method.as_mut | ||
| /// [`as_uninit_mut`]: #method.as_uninit_mut | ||
| /// [`as_ref_unchecked`]: #method.as_mut_unchecked | ||
| /// | ||
| /// # Safety | ||
| /// | ||
| /// When calling this method, you have to ensure that all of the following is true: | ||
| /// | ||
| /// * The pointer must be properly aligned. | ||
| /// | ||
| /// * It must be "dereferenceable" in the sense defined in [the module documentation]. | ||
| /// | ||
| /// * The pointer must point to an initialized instance of `T`. | ||
| /// | ||
| /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is | ||
| /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. | ||
| /// In particular, while this reference exists, the memory the pointer points to must | ||
| /// not get mutated (except inside `UnsafeCell`). | ||
| /// | ||
| /// This applies even if the result of this method is unused! | ||
| /// (The part about being initialized is not yet fully decided, but until | ||
| /// it is, the only safe approach is to ensure that they are indeed initialized.) | ||
| /// | ||
| /// [the module documentation]: crate::ptr#safety |
There was a problem hiding this comment.
My comments from before etc.
|
@rustbot author |
rustbot
added
S-waiting-on-author
|
@GrigorenkoPV any updates on this? thanks |
|
I hope my feedback wasn't overwhelming. ^^; I would be okay with deferring many of these questions to later if issues were opened for each. I also reviewed the generated HTML and dismissed one of my own questions. |
|
Oh wow, it has been 1½ months already. Sorry, got caught up with IRL shenanigans. Anyways DocumentationIndeed, an overhaul is needed. What needs to be doneI would argue that the documentation pieces for
should stay more or less in sync, so it doesn't really make sense to modify half of those without modifying the others. On top of that, it's probably not going to be a trivial fix, because there's quite a few problems to address:
This PR?With that said, I feel like non-trivial changes to existing documentation is out of scope for a PR simply implementing some counterparts for existing APIs. Counterargument: this PR doubles the amount of flawed documentation, reaching the critical mass, so it should resolve this issue or at least be blocked on it. In any case, I don't feel like I would be able to tackle the documentation issues, so I am asking anyone else to approach this if they are willing to do so. So, should I open a separate issue? Is this PR blocked until the issue is resolved, or can we move on in the meantime? Const-stability
Yes, I would say so. All of the
Well, #91822 already got notified because I mentioned it in code, but I will mention it once more right now. I am also going to ask to update the tracking issue OP when and if this PR gets merged using this feature gate. Beep-boop@rustbot review |
rustbot
added
S-waiting-on-review
Ah okay, cool!
Okay, if we're tabling any (heh) issues for later, then yes I would like them on the issue tracker. Either as separate issues or a single issue with todo bullets or whatever other division you think most suits. Regarding one thing, the doctests: those will be using this API specifically, and I would say there is an argument that, as the return type is literally not the same, there is every reason to make the doctests fairly distinct. At the very least, there should be tests that assert on certain uses for
Would you be willing to make that happen? I don't even care about the randomly hidden array, tbh. |
Done: #124669 |
|
Okay |
bors
added
S-waiting-on-bors
… r=workingjubilee Implement ptr_as_ref_unchecked Implementation of rust-lang#122034. Prefixed the feature name with `ptr_` for clarity. Linked const-unstability to rust-lang#91822, so the post there should probably be updated to mentions the 3 new methods when/if this PR is merged.
… r=workingjubilee Implement ptr_as_ref_unchecked Implementation of rust-lang#122034. Prefixed the feature name with `ptr_` for clarity. Linked const-unstability to rust-lang#91822, so the post there should probably be updated to mentions the 3 new methods when/if this PR is merged.
…iaskrgr Rollup of 7 pull requests Successful merges: - rust-lang#122492 (Implement ptr_as_ref_unchecked) - rust-lang#123815 (Fix cannot usage in time.rs) - rust-lang#124059 (default_alloc_error_hook: explain difference to default __rdl_oom in alloc) - rust-lang#124510 (Add raw identifier in a typo suggestion) - rust-lang#124555 (coverage: Clean up creation of MC/DC condition bitmaps) - rust-lang#124593 (Describe and use CStr literals in CStr and CString docs) - rust-lang#124630 (CI: remove `env-x86_64-apple-tests` YAML anchor) r? `@ghost` `@rustbot` modify labels: rollup
Rollup merge of rust-lang#122492 - GrigorenkoPV:ptr_as_ref_unchecked, r=workingjubilee Implement ptr_as_ref_unchecked Implementation of rust-lang#122034. Prefixed the feature name with `ptr_` for clarity. Linked const-unstability to rust-lang#91822, so the post there should probably be updated to mentions the 3 new methods when/if this PR is merged.
Implementation of #122034.
Prefixed the feature name with
ptr_for clarity.Linked const-unstability to #91822, so the post there should probably be updated to mentions the 3 new methods when/if this PR is merged.