Again, I'll note that
clone_from_raw was discussed at
increment_ref_count stabilization time, and the general opinion was that having both was fine.
I personally like
clone_from_raw over the raw refcount manipulation, because it's marginally easier (ime) to specify purely in terms of owned/raw handles, and nailing down exactly how to document the safety interactions between
[into|from]_raw was tricky. Whereas
clone_from_raw doesn't require any extra spec work beyond
[into|from]_raw already do, since it gives you a new owned handle. Plus, then,
and the handle management rules fall out cleanly. On top of that, it's not immediately obvious that
decrement_ref_count potentially drops the wrapped
drop(from_raw(ptr)) definitely is.
That said, the trains have left the station, and
[incr|decr]ement_ref_count are stable. This is fine, they're good helpers to have! We've cleared up the handle ownership documentation, and
increment_ref_count is the exact semantics that
RawWaker wants to have.
increment_ref_count was stabilized to serve that specific use case, rather than block on adding
decrement_ref_count was also stabilized as its dual.
clone_from_raw is a higher-level interface that we can and should also provide; it's just nobody has bothered to actually PR it yet.
One note for @Soni: (pointer) provenance has a specific meaning: what memory the pointer is allowed to read from, and what memory it's allowed to write to. I suspect you're also trying to extend this to what "raw handles" to the reference counted object it owns, but that's not how we've specified the ref count management, and I'd be loathe to tie it into provenance which is already a tricky subject.
Roughly, the raw ref counting semantics are specified as:
Arc<T> owns an owned strong handle to the refcounted object.
- When the last owned strong handle is dropped, the object is considered dropped. (An owned handle will always actually perform this drop.)
- In addition to the owned handles owned by the strongly typed
Arc handles, there is a pool of raw owned handles globally available to draw from or add to. (Semantically, you can think of this pool as ghost state living on top of the physical ref count tracking.)
- You may only draw from the raw pool given a pointer with write provenance over the ref count location and type-appropriate shared provenance over the refcounted object.
mem::forgetting a strongly typed owned handle moves it into the raw owned handle pool.
from_rawing a pointer with appropriate provenance moves a raw handle to a strongly typed handle.
increment_ref_count adds a new raw handle to the pool.
decrement_ref_count destroys a raw handle from the pool.
Arc::clone creates a new typed handle given an existing typed handle.
clone_from_raw creates a new typed handle given an existing raw handle.