Skip to content

Commit 394c864

Browse files
lolbinarycatlolbinarycat
committed
remove duplicate explanations of the ptr to ref conversion rules
1 parent 571348b commit 394c864

File tree

4 files changed

+50
-183
lines changed

4 files changed

+50
-183
lines changed

‎core/src/ptr/const_ptr.rs‎

Lines changed: 4 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -239,24 +239,7 @@ impl<T: ?Sized> *const T {
239239
/// # Safety
240240
///
241241
/// When calling this method, you have to ensure that *either* the pointer is null *or*
242-
/// all of the following is true:
243-
///
244-
/// * The pointer must be properly aligned.
245-
///
246-
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
247-
///
248-
/// * The pointer must point to an initialized instance of `T`.
249-
///
250-
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
251-
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
252-
/// In particular, while this reference exists, the memory the pointer points to must
253-
/// not get mutated (except inside `UnsafeCell`).
254-
///
255-
/// This applies even if the result of this method is unused!
256-
/// (The part about being initialized is not yet fully decided, but until
257-
/// it is, the only safe approach is to ensure that they are indeed initialized.)
258-
///
259-
/// [the module documentation]: crate::ptr#safety
242+
/// the pointer is [convirtible to a reference](crate::ptr#pointer-to-reference-conversion)
260243
///
261244
/// # Examples
262245
///
@@ -302,24 +285,8 @@ impl<T: ?Sized> *const T {
302285
///
303286
/// # Safety
304287
///
305-
/// When calling this method, you have to ensure that all of the following is true:
306-
///
307-
/// * The pointer must be properly aligned.
308-
///
309-
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
310-
///
311-
/// * The pointer must point to an initialized instance of `T`.
312-
///
313-
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
314-
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
315-
/// In particular, while this reference exists, the memory the pointer points to must
316-
/// not get mutated (except inside `UnsafeCell`).
317-
///
318-
/// This applies even if the result of this method is unused!
319-
/// (The part about being initialized is not yet fully decided, but until
320-
/// it is, the only safe approach is to ensure that they are indeed initialized.)
321-
///
322-
/// [the module documentation]: crate::ptr#safety
288+
/// When calling this method, you have to ensure that
289+
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion)
323290
///
324291
/// # Examples
325292
///
@@ -350,20 +317,7 @@ impl<T: ?Sized> *const T {
350317
/// # Safety
351318
///
352319
/// When calling this method, you have to ensure that *either* the pointer is null *or*
353-
/// all of the following is true:
354-
///
355-
/// * The pointer must be properly aligned.
356-
///
357-
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
358-
///
359-
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
360-
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
361-
/// In particular, while this reference exists, the memory the pointer points to must
362-
/// not get mutated (except inside `UnsafeCell`).
363-
///
364-
/// This applies even if the result of this method is unused!
365-
///
366-
/// [the module documentation]: crate::ptr#safety
320+
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion)
367321
///
368322
/// # Examples
369323
///

‎core/src/ptr/mod.rs‎

Lines changed: 26 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -57,21 +57,39 @@
5757
//! [`NonNull::dangling`] in such cases.
5858
//!
5959
//! ## Pointer to reference conversion
60-
//! When converting a pointer to a reference using `&*`, there are several
61-
//! rules that must be followed:
60+
//! When converting a pointer to a reference `&T` using `&*`,
61+
//! there are several rules that must be followed:
62+
//!
6263
//! * The pointer must be properly aligned.
6364
//!
64-
//! * It must be "dereferenceable" in the sense defined above
65+
// some microprocessors may use address 0 for an interrupt vector.
66+
// users of these microprocessors must always read/write address 0 through
67+
// a raw pointer, not a reference.
68+
//! * It must be non-null.
69+
//!
70+
//! * It must be "dereferenceable" in the sense defined above.
6571
//!
66-
//! * The pointer must point to an initialized instance of `T`.
72+
//! * The pointer must point to a valid instance of `T`.
73+
//! This means that the created reference can only refer to
74+
//! uninitialized memory through careful use of `MaybeUninit`.
6775
//!
68-
//! * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
69-
//! arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
70-
//! In particular, while this reference exists, the memory the pointer points to must
71-
//! not get accessed (read or written) through any other pointer.
76+
//! * You must enforce Rust's aliasing rules, since the lifetime of the
77+
//! created reference is arbitrarily chosen,
78+
//! and does not necessarily reflect the actual lifetime of the data.
79+
//! In particular, while this reference exists,
80+
//! the memory the pointer points to must
81+
//! not get accessed (read or written) through any raw pointer,
82+
//! except for data inside an `UnsafeCell`
83+
// ^ previous documentation was somewhat unclear on if modifications through
84+
// an UnsafeCell are safe even if they would seemingly violate the exclusivity
85+
// of a mut ref.
7286
//!
7387
//! If a pointer follows all of these rules, it is said to be
7488
//! *convertable to a reference*.
89+
// ^ we use this term instead of saying that the produced reference must
90+
// be valid, as the validity of a reference is easily confused for the
91+
// validity of the thing it refers to, and while the two concepts are
92+
// closly related, they are not identical.
7593
//!
7694
//! These apply even if the result is unused!
7795
//! (The part about being initialized is not yet fully decided, but until

‎core/src/ptr/mut_ptr.rs‎

Lines changed: 8 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -296,24 +296,7 @@ impl<T: ?Sized> *mut T {
296296
///
297297
/// # Safety
298298
///
299-
/// When calling this method, you have to ensure that all of the following is true:
300-
///
301-
/// * The pointer must be properly aligned.
302-
///
303-
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
304-
///
305-
/// * The pointer must point to an initialized instance of `T`.
306-
///
307-
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
308-
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
309-
/// In particular, while this reference exists, the memory the pointer points to must
310-
/// not get mutated (except inside `UnsafeCell`).
311-
///
312-
/// This applies even if the result of this method is unused!
313-
/// (The part about being initialized is not yet fully decided, but until
314-
/// it is, the only safe approach is to ensure that they are indeed initialized.)
315-
///
316-
/// [the module documentation]: crate::ptr#safety
299+
/// When calling this method, you have to ensure that the pointer is [convirtible to a reference](crate::ptr#pointer-to-reference-conversion)
317300
///
318301
/// # Examples
319302
///
@@ -347,20 +330,9 @@ impl<T: ?Sized> *mut T {
347330
/// # Safety
348331
///
349332
/// When calling this method, you have to ensure that *either* the pointer is null *or*
350-
/// all of the following is true:
351-
///
352-
/// * The pointer must be properly aligned.
353-
///
354-
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
355-
///
356-
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
357-
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
358-
/// In particular, while this reference exists, the memory the pointer points to must
359-
/// not get mutated (except inside `UnsafeCell`).
360-
///
361-
/// This applies even if the result of this method is unused!
362-
///
363-
/// [the module documentation]: crate::ptr#safety
333+
/// the pointer is [convirtible to a reference](crate::ptr#pointer-to-reference-conversion).
334+
/// Note that because the created reference is to `MaybeUninit<T>`, the
335+
/// source pointer can point to uninitialized memory.
364336
///
365337
/// # Examples
366338
///
@@ -594,7 +566,7 @@ impl<T: ?Sized> *mut T {
594566
///
595567
/// When calling this method, you have to ensure that *either*
596568
/// the pointer is null *or*
597-
/// the pointer is [convirtible to a reference](crate::ptr#pointer-to-reference-conversion)
569+
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion)
598570
///
599571
///
600572
/// # Examples
@@ -643,24 +615,8 @@ impl<T: ?Sized> *mut T {
643615
///
644616
/// # Safety
645617
///
646-
/// When calling this method, you have to ensure that all of the following is true:
647-
///
648-
/// * The pointer must be properly aligned.
649-
///
650-
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
651-
///
652-
/// * The pointer must point to an initialized instance of `T`.
653-
///
654-
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
655-
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
656-
/// In particular, while this reference exists, the memory the pointer points to must
657-
/// not get mutated (except inside `UnsafeCell`).
658-
///
659-
/// This applies even if the result of this method is unused!
660-
/// (The part about being initialized is not yet fully decided, but until
661-
/// it is, the only safe approach is to ensure that they are indeed initialized.)
662-
///
663-
/// [the module documentation]: crate::ptr#safety
618+
/// When calling this method, you have to ensure that
619+
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion)
664620
///
665621
/// # Examples
666622
///
@@ -695,20 +651,7 @@ impl<T: ?Sized> *mut T {
695651
/// # Safety
696652
///
697653
/// When calling this method, you have to ensure that *either* the pointer is null *or*
698-
/// all of the following is true:
699-
///
700-
/// * The pointer must be properly aligned.
701-
///
702-
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
703-
///
704-
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
705-
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
706-
/// In particular, while this reference exists, the memory the pointer points to must
707-
/// not get accessed (read or written) through any other pointer.
708-
///
709-
/// This applies even if the result of this method is unused!
710-
///
711-
/// [the module documentation]: crate::ptr#safety
654+
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion)
712655
#[inline]
713656
#[unstable(feature = "ptr_as_uninit", issue = "75402")]
714657
#[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]

‎core/src/ptr/non_null.rs‎

Lines changed: 12 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -128,20 +128,10 @@ impl<T: Sized> NonNull<T> {
128128
///
129129
/// # Safety
130130
///
131-
/// When calling this method, you have to ensure that all of the following is true:
132-
///
133-
/// * The pointer must be properly aligned.
134-
///
135-
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
136-
///
137-
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
138-
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
139-
/// In particular, while this reference exists, the memory the pointer points to must
140-
/// not get mutated (except inside `UnsafeCell`).
141-
///
142-
/// This applies even if the result of this method is unused!
143-
///
144-
/// [the module documentation]: crate::ptr#safety
131+
/// When calling this method, you have to ensure that
132+
/// the pointer is [convirtible to a reference](crate::ptr#pointer-to-reference-conversion).
133+
/// Note that because the created reference is to `MaybeUninit<T>`, the
134+
/// source pointer can point to uninitialized memory.
145135
#[inline]
146136
#[must_use]
147137
#[unstable(feature = "ptr_as_uninit", issue = "75402")]
@@ -162,20 +152,10 @@ impl<T: Sized> NonNull<T> {
162152
///
163153
/// # Safety
164154
///
165-
/// When calling this method, you have to ensure that all of the following is true:
166-
///
167-
/// * The pointer must be properly aligned.
168-
///
169-
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
170-
///
171-
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
172-
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
173-
/// In particular, while this reference exists, the memory the pointer points to must
174-
/// not get accessed (read or written) through any other pointer.
175-
///
176-
/// This applies even if the result of this method is unused!
177-
///
178-
/// [the module documentation]: crate::ptr#safety
155+
/// When calling this method, you have to ensure that
156+
/// the pointer is [convirtible to a reference](crate::ptr#pointer-to-reference-conversion).
157+
/// Note that because the created reference is to `MaybeUninit<T>`, the
158+
/// source pointer can point to uninitialized memory.
179159
#[inline]
180160
#[must_use]
181161
#[unstable(feature = "ptr_as_uninit", issue = "75402")]
@@ -361,22 +341,8 @@ impl<T: ?Sized> NonNull<T> {
361341
///
362342
/// # Safety
363343
///
364-
/// When calling this method, you have to ensure that all of the following is true:
365-
///
366-
/// * The pointer must be properly aligned.
367-
///
368-
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
369-
///
370-
/// * The pointer must point to an initialized instance of `T`.
371-
///
372-
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
373-
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
374-
/// In particular, while this reference exists, the memory the pointer points to must
375-
/// not get mutated (except inside `UnsafeCell`).
376-
///
377-
/// This applies even if the result of this method is unused!
378-
/// (The part about being initialized is not yet fully decided, but until
379-
/// it is, the only safe approach is to ensure that they are indeed initialized.)
344+
/// When calling this method, you have to ensure that
345+
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion)
380346
///
381347
/// # Examples
382348
///
@@ -412,22 +378,8 @@ impl<T: ?Sized> NonNull<T> {
412378
///
413379
/// # Safety
414380
///
415-
/// When calling this method, you have to ensure that all of the following is true:
416-
///
417-
/// * The pointer must be properly aligned.
418-
///
419-
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
420-
///
421-
/// * The pointer must point to an initialized instance of `T`.
422-
///
423-
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
424-
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
425-
/// In particular, while this reference exists, the memory the pointer points to must
426-
/// not get accessed (read or written) through any other pointer.
427-
///
428-
/// This applies even if the result of this method is unused!
429-
/// (The part about being initialized is not yet fully decided, but until
430-
/// it is, the only safe approach is to ensure that they are indeed initialized.)
381+
/// When calling this method, you have to ensure that
382+
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion)
431383
/// # Examples
432384
///
433385
/// ```

0 commit comments

Comments
 (0)