Rollup merge of #53782 - rask:task/arc-docs-adjustment, r=cramertj

Make Arc cloning mechanics clearer in module docs

Add some more wording to module documentation regarding how
`Arc::clone()` works, as some users have assumed cloning Arc's
to work via dereferencing to inner value as follows:

    use std::sync::Arc;

    let myarc = Arc::new(1);
    let myarcref = myarc.clone();

    assert!(1 == myarcref);

Instead of the actual mechanic of referencing the existing
Arc value:

    use std::sync::Arg;

    let myarc = Arc::new(1);
    let myarcref = myarc.clone();

    assert!(myarcref == &myarc); // not sure if assert could assert this in the real world
This commit is contained in:
kennytm 2018-09-01 21:14:13 +08:00 committed by GitHub
commit fcd76b4d3c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -49,9 +49,10 @@ const MAX_REFCOUNT: usize = (isize::MAX) as usize;
/// ///
/// The type `Arc<T>` provides shared ownership of a value of type `T`, /// The type `Arc<T>` provides shared ownership of a value of type `T`,
/// allocated in the heap. Invoking [`clone`][clone] on `Arc` produces /// allocated in the heap. Invoking [`clone`][clone] on `Arc` produces
/// a new pointer to the same value in the heap. When the last `Arc` /// a new `Arc` instance, which points to the same value on the heap as the
/// pointer to a given value is destroyed, the pointed-to value is /// source `Arc`, while increasing a reference count. When the last `Arc`
/// also destroyed. /// pointer to a given value is destroyed, the pointed-to value is also
/// destroyed.
/// ///
/// Shared references in Rust disallow mutation by default, and `Arc` is no /// Shared references in Rust disallow mutation by default, and `Arc` is no
/// exception: you cannot generally obtain a mutable reference to something /// exception: you cannot generally obtain a mutable reference to something
@ -107,7 +108,7 @@ const MAX_REFCOUNT: usize = (isize::MAX) as usize;
/// // The two syntaxes below are equivalent. /// // The two syntaxes below are equivalent.
/// let a = foo.clone(); /// let a = foo.clone();
/// let b = Arc::clone(&foo); /// let b = Arc::clone(&foo);
/// // a and b both point to the same memory location as foo. /// // a, b, and foo are all Arcs that point to the same memory location
/// ``` /// ```
/// ///
/// The [`Arc::clone(&from)`] syntax is the most idiomatic because it conveys more explicitly /// The [`Arc::clone(&from)`] syntax is the most idiomatic because it conveys more explicitly