r? @dtolnay

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

cc @CAD97

Rather than try to line-comment, here's my take on the same information; perhaps you can find a happy medium somewhere.

into_raw:

Consumes the Weak<T> and turns it into a raw pointer.

This converts the weak pointer into a raw pointer, suspending ownership of the weak pointer. It can be turned back into the Weak<T>, reclaiming the suspended ownership, via [from_raw].

...

from_raw:

Converts a raw pointer previously created by [into_raw] back into Weak<T>.

...

It reclaims the ownership of the weak reference previously suspended with into_raw (with the exception of pointers created by [new], as these don't actually own any data).

Safety

The pointer must have originated from [into_raw] and there must be a suspended weak reference to reclaim.

It is allowed for the strong count to be 0 at the time of calling this. However, there must have been a previous matching call to [into_raw] to suspend ownership of a weak reference, which is reclaimed by this function (with the exception dangling Weak created by [new], which do not own any data).

...

And I hoped navigating the pitfalls of unsafety in the implementation would be the hard part of the feature 😇

OK, I've tried to rewrite it while avoiding any kind of new terminology (like suspending), intuitive descriptions of frozen, etc. I hope it's still readable and no standard-lawyer can prove it does something else than it does.

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

Rebased on that big-bang move everything PR. Sorry if it makes the reviewing harder, but I think it should not be a big problem with changes this small and incremental reviewing doesn't really help here.

@bors r+ rollup

📌 Commit ad6d63e has been approved by dtolnay

⌛ Testing commit ad6d63e with merge 45a9dbd0690ffc6b75d596689c1a2e6841fff5a1...

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

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 @rust-lang/infra. (Feature Requests)

💔 Test failed - checks-actions

I'm trying to look at what failed on CI. I don't know for sure, but it seems like it fails on downloading some docker image?

This looks like an internal error from crates.io, nothing to do with your PR.

warning: spurious network error (2 tries remaining): failed to get 200 response from `https://crates.io/api/v1/crates/term/0.6.0/download`, got 502
warning: spurious network error (1 tries remaining): failed to get 200 response from `https://crates.io/api/v1/crates/term/0.6.0/download`, got 502
error: failed to download from `https://crates.io/api/v1/crates/term/0.6.0/download`

@bors retry

⌛ Testing commit ad6d63e with merge e532d6541289e12b5586f3a1f63f0153a45e6233...

💥 Test timed out

65 completed jobs
in 1h 56m 31s

In what way did this time out?

Oh, x86_64-apple on Azure timed out after five hours: https://github.com/rust-lang-ci/rust/runs/926325983

This can't possibly be the cause of any failures/timeouts, though, it's just a doc change.

@bors rollup=always

(I don't know if r+ rollup sets always but just in case (oh could've sworn bors let me rollup my own PR; guess that's a special case))

@CAD97: 🔑 Insufficient privileges: not in try users

@bors retry