Stabilise weak_ptr_eq

[Thomasdezeeuw]

Implemented in #55987.

Closes #55981.

[rust-highfive]

r? @kennytm

(rust_highfive has picked a reviewer for you, use r? to override)

[rust-highfive]

The job x86_64-gnu-llvm-6.0 of your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

travis_time:end:0422dee9:start=1560421574970719878,finish=1560421575726646528,duration=755926650
$ git checkout -qf FETCH_HEAD
travis_fold:end:git.checkout

Encrypted environment variables have been removed for security reasons.
See https://docs.travis-ci.com/user/pull-requests/#pull-requests-and-security-restrictions
$ export SCCACHE_BUCKET=rust-lang-ci-sccache2
$ export SCCACHE_REGION=us-west-1
$ export GCP_CACHE_BUCKET=rust-lang-ci-cache
$ export AWS_ACCESS_KEY_ID=AKIA46X5W6CZEJZ6XT55
---
travis_time:start:tidy
tidy check
[00:04:44] * 576 error codes
[00:04:44] * highest error code: E0731
[00:04:46] tidy error: /checkout/src/liballoc/rc.rs:1545: malformed stability attribute: missing the `since` key
[00:04:46] tidy error: /checkout/src/liballoc/sync.rs:1379: malformed stability attribute: missing the `since` key
[00:04:49] some tidy checks failed
[00:04:49] 
[00:04:49] 
[00:04:49] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/tidy" "/checkout/src" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "--no-vendor" "--quiet"
[00:04:49] 
[00:04:49] 
[00:04:49] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test src/tools/tidy
[00:04:49] Build completed unsuccessfully in 0:01:13

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

[Thomasdezeeuw]

I think the failure is unrelated to this pr.

[chpio]

Can we first change the method into a normal method (taking &self) instead of an associated function (taking this: &Self)?

[bors]

☔ The latest upstream changes (presumably #61915) made this pull request unmergeable. Please resolve the merge conflicts.

[Centril]

r? @sfackler

cc @RalfJung, I'd appreciate a review from you also :)

[RalfJung]

There's not much code to look at, that seems fine. ;)

The docs could be improved though IMO. It first says "Returns true if the two Weaks point to the same value" only to later (in a separate subsection!) note that it also works for Weak::new that do not point to any value -- which seems to contradict the first statement. And moreover, there is no mention of what happens when comparing a Weak that is "dangling" in the sense that upgrade would fail -- there's no value in that case either.

I think Rc::ptr_eq's doc is similarly confusing. I'd argue e.g. that "5" and "5" are the same value, and still the doctest has assert!(!Rc::ptr_eq(&five, &other_five)). Actually it seems like the entire Rc docs use "value" as word for "RcBox instance". IMO that's a very bad choice of words as Rust already uses the same term for a very different meaning.

A better term might be "reference-counted object".

[Thomasdezeeuw]

@RalfJung

The docs could be improved though IMO. It first says "Returns true if the two Weaks point to the same value" only to later (in a separate subsection!) note that it also works for Weak::new that do not point to any value -- which seems to contradict the first statement. And moreover, there is no mention of what happens when comparing a Weak that is "dangling" in the sense that upgrade would fail -- there's no value in that case either.

I mostly copied the documentation from Rc::ptr_eq, which always points to a value to the "dangling" case didn't apply there. For Weak I've added the notes section for this. However you did leave a fairly important part of the docs out in your comment, it says:

Returns true if the two Weaks point to the same value (not just values that compare as equal).

(emphasis mine)

The part in between brackets is arguably the most important part, maybe that should be moved to the forefront of the sentence more.

I think Rc::ptr_eq's doc is similarly confusing. I'd argue e.g. that "5" and "5" are the same value, and still the doctest has assert!(!Rc::ptr_eq(&five, &other_five)). Actually it seems like the entire Rc docs use "value" as word for "RcBox instance". IMO that's a very bad choice of words as Rust already uses the same term for a very different meaning.

I agree with this, what do you suggest as concrete improvement?

[RalfJung]

However you did leave a fairly important part of the docs out in your comment, it says:

That was deliberate; as I explained above, values that "compare equal but are not the same" is an odd concept. It indicates that the mathematical integer value "5" might have more to its "identity" that the fact that it is 5? Or maybe integers have provenance?

I know what the text means, but I don't think the parenthetical helps. This is the old problem of comparing values vs. comparing locations (addresses) that hold values, except that it uses exactly the wrong term for what this code really does.

[Thomasdezeeuw]

I agree with your point. What terminology should be used instead? Should "values" not be mentioned at all perhaps and only talk of pointers? I'm really looking for some concrete documentation changes and any help here would be appreciated.

[RalfJung]

what do you suggest as concrete improvement?

strawman proposal: "reference-counted object".

[RalfJung]

Alternatively we could be talking about comparing things "by their address", as we do in ptr::eq. But then the question remains "the address of what", and that's where something like "reference-counted object" would come up again.

[Thomasdezeeuw]

@RalfJung what do you think about the following?

    /// Returns `true` if the address of the two reference counted objects (the
    /// `Weaks`) are equal.
    ///
    /// # Notes
    ///
    /// Since this compares addresses it means that `Weak::new()` will always
    /// equal each other.

Also do you want me to make the change to Arc::ptr_eq and Rc::ptr_eq as well?

[RalfJung]

The parenthetical is odd -- the object itself isn't weak, only the reference is.

Also do you want me to make the change to Arc::ptr_eq and Rc::ptr_eq as well?

Yes, this should be done consistently.

[rfcbot]

Team member @sfackler has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @Kimundi
• @SimonSapin
• @alexcrichton
• @dtolnay
• @sfackler
• @withoutboats

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[SimonSapin]

Is the Weak::new question resolved?

[RalfJung]

The edit I suggested at #61797 (comment) is still outstanding.

[Thomasdezeeuw]

I've just messed up this branch, will fix it asap.

[Thomasdezeeuw]

I've just rebased on master, update the stable attribute to 1.39 and added the doc changes as requested by @RalfJung.

[Thomasdezeeuw]

@SimonSapin I think the Weak::new() question is resolved with the documentation and examples.

[RalfJung]

r=me: Docs look good enough for me (the entire Rc/Arc "value" terminology could be improved but that's a separate issue).

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

The RFC will be merged soon.

[Centril]

@bors r=RalfJung rollup

[bors]

📌 Commit 307804a has been approved by RalfJung