Documenting the case of Weak::upgrade returning None when the value behind the reference is missing

[quixoticaxis]

Adds a clause to the documentation of Weak for Arc which was discussed in #154936.

Adds the same clause to the documentation of Weak for Rc, because the behavior is the same.

[rustbot]

r? @jhpratt

rustbot has assigned @jhpratt.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: libs
• libs expanded to 7 candidates
• Random selection from Mark-Simulacrum, jhpratt

[quixoticaxis]

View changes since the review

Technically, there is a third nightly-only case for Weak::upgrade returning None for Rc when the reference has been created by calling new_in, but I'm not sure how and whether it should be explicitely mentioned.

[zachs18]

new_in is the allocator_api analogue of the stable Weak::new, for which upgrade has the same behavior.

Maybe something like

Returns [None] if the inner value has since been dropped or moved out, or if this Weak does not point to an allocation.

[zachs18]

There's also the unstable case of a Weak created from UniqueRc::downgrade where the UniqueRc hasn't yet been turned into an Rc, for which the inner value hasn't been dropped or moved out, but something else currently owns it.

[quixoticaxis]

@zachs18 updated the comment both for Rc and Arc.

[quixoticaxis]

There's also the unstable case of a Weak created from UniqueRc::downgrade where the UniqueRc hasn't yet been turned into an Rc, for which the inner value hasn't been dropped or moved out, but something else currently owns it.

I suppose the same goes for the upgrades from within the new_cyclic callback. Should it become a list at this point?

Returns [None] in the following cases:

• the inner value has since been dropped or moved out
• this Weak does not point to an allocation
• the owning reference this Weak is assosiated with is either not fully constructed or does not allow an upgrade.

[quixoticaxis]

I'm not sure what tidy does not like now.

[zachs18]

You can run ./x test tidy locally, and it shows the issue highlighted with ANSI terminal color.

The specific issue here is that there is trailing whitespace on those lines.

You can use ./x test tidy --bless to remove the trailing whitespace.

You can also install a git hook so that git will error if you try to push code that fails tidy: https://rustc-dev-guide.rust-lang.org/building/suggested.html#installing-a-pre-push-hook