Skip to content

Commit 9474c74

Browse files
matthiaskrgrmatthiaskrgr
authored
Rollup merge of #93109 - JakobDegen:arc-docs, r=m-ou-se
Improve `Arc` and `Rc` documentation This makes two changes (I can split the PR if necessary, but the changes are pretty small): 1. A bunch of trait implementations claimed to be zero cost; however, they use the `Arc<T>: From<Box<T>>` impl which is definitely not free, especially for large dynamically sized `T`. 2. The code in deferred initialization examples unnecessarily used excessive amounts of `unsafe`. This has been reduced.
2 parents ab19d4a + 4de7618 commit 9474c74

File tree

5 files changed

+55
-65
lines changed

5 files changed

+55
-65
lines changed

‎library/alloc/src/rc.rs

+21-29
Original file line numberDiff line numberDiff line change
@@ -451,12 +451,10 @@ impl<T> Rc<T> {
451451
///
452452
/// let mut five = Rc::<u32>::new_uninit();
453453
///
454-
/// let five = unsafe {
455-
/// // Deferred initialization:
456-
/// Rc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);
454+
/// // Deferred initialization:
455+
/// Rc::get_mut(&mut five).unwrap().write(5);
457456
///
458-
/// five.assume_init()
459-
/// };
457+
/// let five = unsafe { five.assume_init() };
460458
///
461459
/// assert_eq!(*five, 5)
462460
/// ```
@@ -543,12 +541,10 @@ impl<T> Rc<T> {
543541
///
544542
/// let mut five = Rc::<u32>::try_new_uninit()?;
545543
///
546-
/// let five = unsafe {
547-
/// // Deferred initialization:
548-
/// Rc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);
544+
/// // Deferred initialization:
545+
/// Rc::get_mut(&mut five).unwrap().write(5);
549546
///
550-
/// five.assume_init()
551-
/// };
547+
/// let five = unsafe { five.assume_init() };
552548
///
553549
/// assert_eq!(*five, 5);
554550
/// # Ok::<(), std::alloc::AllocError>(())
@@ -660,14 +656,13 @@ impl<T> Rc<[T]> {
660656
///
661657
/// let mut values = Rc::<[u32]>::new_uninit_slice(3);
662658
///
663-
/// let values = unsafe {
664-
/// // Deferred initialization:
665-
/// Rc::get_mut_unchecked(&mut values)[0].as_mut_ptr().write(1);
666-
/// Rc::get_mut_unchecked(&mut values)[1].as_mut_ptr().write(2);
667-
/// Rc::get_mut_unchecked(&mut values)[2].as_mut_ptr().write(3);
659+
/// // Deferred initialization:
660+
/// let data = Rc::get_mut(&mut values).unwrap();
661+
/// data[0].write(1);
662+
/// data[1].write(2);
663+
/// data[2].write(3);
668664
///
669-
/// values.assume_init()
670-
/// };
665+
/// let values = unsafe { values.assume_init() };
671666
///
672667
/// assert_eq!(*values, [1, 2, 3])
673668
/// ```
@@ -738,12 +733,10 @@ impl<T> Rc<mem::MaybeUninit<T>> {
738733
///
739734
/// let mut five = Rc::<u32>::new_uninit();
740735
///
741-
/// let five = unsafe {
742-
/// // Deferred initialization:
743-
/// Rc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);
736+
/// // Deferred initialization:
737+
/// Rc::get_mut(&mut five).unwrap().write(5);
744738
///
745-
/// five.assume_init()
746-
/// };
739+
/// let five = unsafe { five.assume_init() };
747740
///
748741
/// assert_eq!(*five, 5)
749742
/// ```
@@ -777,14 +770,13 @@ impl<T> Rc<[mem::MaybeUninit<T>]> {
777770
///
778771
/// let mut values = Rc::<[u32]>::new_uninit_slice(3);
779772
///
780-
/// let values = unsafe {
781-
/// // Deferred initialization:
782-
/// Rc::get_mut_unchecked(&mut values)[0].as_mut_ptr().write(1);
783-
/// Rc::get_mut_unchecked(&mut values)[1].as_mut_ptr().write(2);
784-
/// Rc::get_mut_unchecked(&mut values)[2].as_mut_ptr().write(3);
773+
/// // Deferred initialization:
774+
/// let data = Rc::get_mut(&mut values).unwrap();
775+
/// data[0].write(1);
776+
/// data[1].write(2);
777+
/// data[2].write(3);
785778
///
786-
/// values.assume_init()
787-
/// };
779+
/// let values = unsafe { values.assume_init() };
788780
///
789781
/// assert_eq!(*values, [1, 2, 3])
790782
/// ```

‎library/alloc/src/sync.rs

+21-29
Original file line numberDiff line numberDiff line change
@@ -437,12 +437,10 @@ impl<T> Arc<T> {
437437
///
438438
/// let mut five = Arc::<u32>::new_uninit();
439439
///
440-
/// let five = unsafe {
441-
/// // Deferred initialization:
442-
/// Arc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);
440+
/// // Deferred initialization:
441+
/// Arc::get_mut(&mut five).unwrap().write(5);
443442
///
444-
/// five.assume_init()
445-
/// };
443+
/// let five = unsafe { five.assume_init() };
446444
///
447445
/// assert_eq!(*five, 5)
448446
/// ```
@@ -545,12 +543,10 @@ impl<T> Arc<T> {
545543
///
546544
/// let mut five = Arc::<u32>::try_new_uninit()?;
547545
///
548-
/// let five = unsafe {
549-
/// // Deferred initialization:
550-
/// Arc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);
546+
/// // Deferred initialization:
547+
/// Arc::get_mut(&mut five).unwrap().write(5);
551548
///
552-
/// five.assume_init()
553-
/// };
549+
/// let five = unsafe { five.assume_init() };
554550
///
555551
/// assert_eq!(*five, 5);
556552
/// # Ok::<(), std::alloc::AllocError>(())
@@ -652,14 +648,13 @@ impl<T> Arc<[T]> {
652648
///
653649
/// let mut values = Arc::<[u32]>::new_uninit_slice(3);
654650
///
655-
/// let values = unsafe {
656-
/// // Deferred initialization:
657-
/// Arc::get_mut_unchecked(&mut values)[0].as_mut_ptr().write(1);
658-
/// Arc::get_mut_unchecked(&mut values)[1].as_mut_ptr().write(2);
659-
/// Arc::get_mut_unchecked(&mut values)[2].as_mut_ptr().write(3);
651+
/// // Deferred initialization:
652+
/// let data = Arc::get_mut(&mut values).unwrap();
653+
/// data[0].write(1);
654+
/// data[1].write(2);
655+
/// data[2].write(3);
660656
///
661-
/// values.assume_init()
662-
/// };
657+
/// let values = unsafe { values.assume_init() };
663658
///
664659
/// assert_eq!(*values, [1, 2, 3])
665660
/// ```
@@ -730,12 +725,10 @@ impl<T> Arc<mem::MaybeUninit<T>> {
730725
///
731726
/// let mut five = Arc::<u32>::new_uninit();
732727
///
733-
/// let five = unsafe {
734-
/// // Deferred initialization:
735-
/// Arc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);
728+
/// // Deferred initialization:
729+
/// Arc::get_mut(&mut five).unwrap().write(5);
736730
///
737-
/// five.assume_init()
738-
/// };
731+
/// let five = unsafe { five.assume_init() };
739732
///
740733
/// assert_eq!(*five, 5)
741734
/// ```
@@ -770,14 +763,13 @@ impl<T> Arc<[mem::MaybeUninit<T>]> {
770763
///
771764
/// let mut values = Arc::<[u32]>::new_uninit_slice(3);
772765
///
773-
/// let values = unsafe {
774-
/// // Deferred initialization:
775-
/// Arc::get_mut_unchecked(&mut values)[0].as_mut_ptr().write(1);
776-
/// Arc::get_mut_unchecked(&mut values)[1].as_mut_ptr().write(2);
777-
/// Arc::get_mut_unchecked(&mut values)[2].as_mut_ptr().write(3);
766+
/// // Deferred initialization:
767+
/// let data = Arc::get_mut(&mut values).unwrap();
768+
/// data[0].write(1);
769+
/// data[1].write(2);
770+
/// data[2].write(3);
778771
///
779-
/// values.assume_init()
780-
/// };
772+
/// let values = unsafe { values.assume_init() };
781773
///
782774
/// assert_eq!(*values, [1, 2, 3])
783775
/// ```

‎library/std/src/ffi/c_str.rs

+4-2
Original file line numberDiff line numberDiff line change
@@ -973,7 +973,8 @@ impl<'a> From<&'a CString> for Cow<'a, CStr> {
973973

974974
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
975975
impl From<CString> for Arc<CStr> {
976-
/// Converts a [`CString`] into an <code>[Arc]<[CStr]></code> without copying or allocating.
976+
/// Converts a [`CString`] into an <code>[Arc]<[CStr]></code> by moving the [`CString`]
977+
/// data into a new [`Arc`] buffer.
977978
#[inline]
978979
fn from(s: CString) -> Arc<CStr> {
979980
let arc: Arc<[u8]> = Arc::from(s.into_inner());
@@ -992,7 +993,8 @@ impl From<&CStr> for Arc<CStr> {
992993

993994
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
994995
impl From<CString> for Rc<CStr> {
995-
/// Converts a [`CString`] into an <code>[Rc]<[CStr]></code> without copying or allocating.
996+
/// Converts a [`CString`] into an <code>[Rc]<[CStr]></code> by moving the [`CString`]
997+
/// data into a new [`Arc`] buffer.
996998
#[inline]
997999
fn from(s: CString) -> Rc<CStr> {
9981000
let rc: Rc<[u8]> = Rc::from(s.into_inner());

‎library/std/src/ffi/os_str.rs

+4-2
Original file line numberDiff line numberDiff line change
@@ -989,7 +989,8 @@ impl Clone for Box<OsStr> {
989989

990990
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
991991
impl From<OsString> for Arc<OsStr> {
992-
/// Converts an [`OsString`] into an <code>[Arc]<[OsStr]></code> without copying or allocating.
992+
/// Converts an [`OsString`] into an <code>[Arc]<[OsStr]></code> by moving the [`OsString`]
993+
/// data into a new [`Arc`] buffer.
993994
#[inline]
994995
fn from(s: OsString) -> Arc<OsStr> {
995996
let arc = s.inner.into_arc();
@@ -1008,7 +1009,8 @@ impl From<&OsStr> for Arc<OsStr> {
10081009

10091010
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
10101011
impl From<OsString> for Rc<OsStr> {
1011-
/// Converts an [`OsString`] into an <code>[Rc]<[OsStr]></code> without copying or allocating.
1012+
/// Converts an [`OsString`] into an <code>[Rc]<[OsStr]></code> by moving the [`OsString`]
1013+
/// data into a new [`Rc`] buffer.
10121014
#[inline]
10131015
fn from(s: OsString) -> Rc<OsStr> {
10141016
let rc = s.inner.into_rc();

‎library/std/src/path.rs

+5-3
Original file line numberDiff line numberDiff line change
@@ -1766,7 +1766,8 @@ impl<'a> From<Cow<'a, Path>> for PathBuf {
17661766

17671767
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
17681768
impl From<PathBuf> for Arc<Path> {
1769-
/// Converts a [`PathBuf`] into an [`Arc`] by moving the [`PathBuf`] data into a new [`Arc`] buffer.
1769+
/// Converts a [`PathBuf`] into an <code>[Arc]<[Path]></code> by moving the [`PathBuf`] data
1770+
/// into a new [`Arc`] buffer.
17701771
#[inline]
17711772
fn from(s: PathBuf) -> Arc<Path> {
17721773
let arc: Arc<OsStr> = Arc::from(s.into_os_string());
@@ -1786,7 +1787,8 @@ impl From<&Path> for Arc<Path> {
17861787

17871788
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
17881789
impl From<PathBuf> for Rc<Path> {
1789-
/// Converts a [`PathBuf`] into an [`Rc`] by moving the [`PathBuf`] data into a new `Rc` buffer.
1790+
/// Converts a [`PathBuf`] into an <code>[Rc]<[Path]></code> by moving the [`PathBuf`] data into
1791+
/// a new [`Rc`] buffer.
17901792
#[inline]
17911793
fn from(s: PathBuf) -> Rc<Path> {
17921794
let rc: Rc<OsStr> = Rc::from(s.into_os_string());
@@ -1796,7 +1798,7 @@ impl From<PathBuf> for Rc<Path> {
17961798

17971799
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
17981800
impl From<&Path> for Rc<Path> {
1799-
/// Converts a [`Path`] into an [`Rc`] by copying the [`Path`] data into a new `Rc` buffer.
1801+
/// Converts a [`Path`] into an [`Rc`] by copying the [`Path`] data into a new [`Rc`] buffer.
18001802
#[inline]
18011803
fn from(s: &Path) -> Rc<Path> {
18021804
let rc: Rc<OsStr> = Rc::from(s.as_os_str());

0 commit comments

Comments
 (0)