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:
Otto Rask 2018-08-29 13:20:56 +03:00
parent f4e981cfe4
commit 5399616f1d

View File

@ -49,9 +49,9 @@
///
/// The type `Arc<T>` provides shared ownership of a value of type `T`,
/// allocated in the heap. Invoking [`clone`][clone] on `Arc` produces
/// a new pointer to the same value in the heap. When the last `Arc`
/// pointer to a given value is destroyed, the pointed-to value is
/// also destroyed.
/// a new pointer to the same `Arc` reference value in the heap. When the last
/// `Arc` 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
/// exception: you cannot generally obtain a mutable reference to something
@ -107,7 +107,8 @@
/// // The two syntaxes below are equivalent.
/// let a = foo.clone();
/// let b = Arc::clone(&foo);
/// // a and b both point to the same memory location as foo.
/// // a and b both point to the same memory location where foo resides
/// // (not where the value wrapped by foo resides).
/// ```
///
/// The [`Arc::clone(&from)`] syntax is the most idiomatic because it conveys more explicitly