OpenE2K/rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Rollup merge of #41240 - projektir:weak_docs, r=alexcrichton

Browse Source 
Updating docs for std::sync::Weak #29377

I will duplicate these changes for [`std::rc::Weak`] if they are approved.

[`std::rc::Weak`]: https://doc.rust-lang.org/std/rc/struct.Weak.html

r? @jonathandturner
This commit is contained in:
Corey Farwell 2017-04-13 13:04:14 -04:00 committed by GitHub
commit 9eb3468e2f
1 changed files with 33 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
src/liballoc/arc.rs
View File

@ -165,18 +165,29 @@ unsafe impl<T: ?Sized + Sync + Send> Sync for Arc<T> {}
#[unstable(feature = "coerce_unsized", issue = "27732")]
impl<T: ?Sized + Unsize<U>, U: ?Sized> CoerceUnsized<Arc<U>> for Arc<T> {}
/// A weak version of [`Arc`][arc].
/// `Weak` is a version of [`Arc`] that holds a non-owning reference to the
/// managed value. The value is accessed by calling [`upgrade`] on the `Weak`
/// pointer, which returns an [`Option`]`<`[`Arc`]`<T>>`.
///
/// `Weak` pointers do not count towards determining if the inner value
/// should be dropped.
/// Since a `Weak` reference does not count towards ownership, it will not
/// prevent the inner value from being dropped, and `Weak` itself makes no
/// guarantees about the value still being present and may return [`None`]
/// when [`upgrade`]d.
///
/// The typical way to obtain a `Weak` pointer is to call
/// [`Arc::downgrade`][downgrade].
/// A `Weak` pointer is useful for keeping a temporary reference to the value
/// within [`Arc`] without extending its lifetime. It is also used to prevent
/// circular references between [`Arc`] pointers, since mutual owning references
/// would never allow either [`Arc`] to be dropped. For example, a tree could
/// have strong [`Arc`] pointers from parent nodes to children, and `Weak`
/// pointers from children back to their parents.
///
/// See the [`Arc`][arc] documentation for more details.
/// The typical way to obtain a `Weak` pointer is to call [`Arc::downgrade`].
///
/// [arc]: struct.Arc.html
/// [downgrade]: struct.Arc.html#method.downgrade
/// [`Arc`]: struct.Arc.html
/// [`Arc::downgrade`]: struct.Arc.html#method.downgrade
/// [`upgrade`]: struct.Weak.html#method.upgrade
/// [`Option`]: ../../std/option/enum.Option.html
/// [`None`]: ../../std/option/enum.Option.html#variant.None
#[stable(feature = "arc_weak", since = "1.4.0")]
pub struct Weak<T: ?Sized> {
ptr: Shared<ArcInner<T>>,
@ -766,14 +777,11 @@ unsafe impl<#[may_dangle] T: ?Sized> Drop for Arc<T> {
}
impl<T> Weak<T> {
/// Constructs a new `Weak<T>`, without an accompanying instance of `T`.
/// Constructs a new `Weak<T>`, allocating memory for `T` without initializing
/// it. Calling [`upgrade`] on the return value always gives [`None`].
///
/// This allocates memory for `T`, but does not initialize it. Calling
/// [`upgrade`][upgrade] on the return value always gives
/// [`None`][option].
///
/// [upgrade]: struct.Weak.html#method.upgrade
/// [option]: ../../std/option/enum.Option.html
/// [`upgrade`]: struct.Weak.html#method.upgrade
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
@ -798,13 +806,13 @@ impl<T> Weak<T> {
}
impl<T: ?Sized> Weak<T> {
/// Upgrades the `Weak` pointer to an [`Arc`][arc], if possible.
/// Attempts to upgrade the `Weak` pointer to an [`Arc`], extending
/// the lifetime of the value if successful.
///
/// Returns [`None`][option] if the strong count has reached zero and the
/// inner value was destroyed.
/// Returns [`None`] if the value has since been dropped.
///
/// [arc]: struct.Arc.html
/// [option]: ../../std/option/enum.Option.html
/// [`Arc`]: struct.Arc.html
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
@ -865,10 +873,7 @@ impl<T: ?Sized> Weak<T> {
#[stable(feature = "arc_weak", since = "1.4.0")]
impl<T: ?Sized> Clone for Weak<T> {
/// Makes a clone of the `Weak` pointer.
///
/// This creates another pointer to the same inner value, increasing the
/// weak reference count.
/// Makes a clone of the `Weak` pointer that points to the same value.
///
/// # Examples
///
@ -900,14 +905,11 @@ impl<T: ?Sized> Clone for Weak<T> {
#[stable(feature = "downgraded_weak", since = "1.10.0")]
impl<T> Default for Weak<T> {
/// Constructs a new `Weak<T>`, without an accompanying instance of `T`.
/// Constructs a new `Weak<T>`, allocating memory for `T` without initializing
/// it. Calling [`upgrade`] on the return value always gives [`None`].
///
/// This allocates memory for `T`, but does not initialize it. Calling
/// [`upgrade`][upgrade] on the return value always gives
/// [`None`][option].
///
/// [upgrade]: struct.Weak.html#method.upgrade
/// [option]: ../../std/option/enum.Option.html
/// [`upgrade`]: struct.Weak.html#method.upgrade
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
@ -926,8 +928,6 @@ impl<T> Default for Weak<T> {
impl<T: ?Sized> Drop for Weak<T> {
/// Drops the `Weak` pointer.
///
/// This will decrement the weak reference count.
///
/// # Examples
///
/// ```