Re: [PATCH v4] rust: move ARef and AlwaysRefCounted to sync::aref

[Benno Lossin]

On Tue Jul 22, 2025 at 12:46 AM CEST, Miguel Ojeda wrote:
> On Tue, Jul 15, 2025 at 1:04 PM Shankari Anand
> <shankari.ak0208@xxxxxxxxx> wrote:
>>
>> +//! Built-in Reference Counting Support
>
> What is it meant by "built-in" here? Could we just use "Reference
> counting support."? Or do you have another suggestion, Benno?

`ARef` specifically is about supporting types that already have their
own "built-in" reference counting. I'm not sure if built-in is the best
word to describe that, some alternatives are inherent or internal.

Maybe we can just expand the module level docs with:

    //! Internal Reference Counting Support.
    //!
    //! Many C types already have their own reference counting mechanism (e.g. by storing a
    //! `refcount_t`). This module provides support for directly using their internal reference count
    //! from Rust; instead of making users have to use an additional Rust-reference count in the form of
    //! [`Arc`].
    //!
    //! The smart pointer [`ARef<T>`] acts similarly to [`Arc<T>`] in that it holds a refcount on the
    //! underlying object, but this refcount is internal to the object. It essentially is a Rust
    //! implementation of the `get_` and `put_` pattern used in C for reference counting.
    //!
    //! To make use of [`ARef<MyType>`], `MyType` needs to implement [`AlwaysRefCounted`]. It is a trait
    //! for accessing the internal reference count of an object of the `MyType` type.

Thoughts?

---
Cheers,
Benno