From 5399616f1d98b4bcc1da87af15f75c95e3c2288b Mon Sep 17 00:00:00 2001 From: Otto Rask Date: Wed, 29 Aug 2018 13:20:56 +0300 Subject: [PATCH 1/3] 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 --- src/liballoc/sync.rs | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/liballoc/sync.rs b/src/liballoc/sync.rs index 2cd7898f4c7..176743fdd1d 100644 --- a/src/liballoc/sync.rs +++ b/src/liballoc/sync.rs @@ -49,9 +49,9 @@ const MAX_REFCOUNT: usize = (isize::MAX) as usize; /// /// The type `Arc` 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 @@ const MAX_REFCOUNT: usize = (isize::MAX) as usize; /// // 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 From 60202199936365e7b2adc70189fbaa664ce729a6 Mon Sep 17 00:00:00 2001 From: Otto Rask Date: Thu, 30 Aug 2018 12:20:41 +0300 Subject: [PATCH 2/3] Rephrase Arc documentation changes regarding clones Make it clearer that `Arc::clone()` in fact creates a whole new Arc with the internal pointer pointing to the same location as the source Arc. --- src/liballoc/sync.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/liballoc/sync.rs b/src/liballoc/sync.rs index 176743fdd1d..72a4740b156 100644 --- a/src/liballoc/sync.rs +++ b/src/liballoc/sync.rs @@ -49,8 +49,9 @@ const MAX_REFCOUNT: usize = (isize::MAX) as usize; /// /// The type `Arc` 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 `Arc` reference value in the heap. When the last -/// `Arc` pointer to a given value is destroyed, the pointed-to value is also +/// a new `Arc` instance, which points to the same value on the heap as the +/// source `Arc`, while increasing a reference count. 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 @@ -107,8 +108,7 @@ const MAX_REFCOUNT: usize = (isize::MAX) as usize; /// // 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 where foo resides -/// // (not where the value wrapped by foo resides). +/// // a and b both point to the same memory location as foo /// ``` /// /// The [`Arc::clone(&from)`] syntax is the most idiomatic because it conveys more explicitly From bf7e324e4e610b1f12971e601073ccfd6f197fff Mon Sep 17 00:00:00 2001 From: Otto Rask Date: Fri, 31 Aug 2018 11:21:01 +0300 Subject: [PATCH 3/3] Add clearer wording to Arc clone example code --- src/liballoc/sync.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/liballoc/sync.rs b/src/liballoc/sync.rs index 72a4740b156..db7a4044b26 100644 --- a/src/liballoc/sync.rs +++ b/src/liballoc/sync.rs @@ -108,7 +108,7 @@ const MAX_REFCOUNT: usize = (isize::MAX) as usize; /// // 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, 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