Strengthening documentation; When to use `Rc` and when to use `AtomicRc` and others

[simnalamburt]

From what I understand, the relationship between circ’s Rc and AtomicRc differs from std’s Rc and Arc. Unlike std::rc::Rc, circ::Rc is thread-safe and resembles a faster version of std::sync::Arc. Despite its name, circ::AtomicRc serves a different role compared to std::sync::Arc, and there is no direct equivalent in std for circ::AtomicRc. It is closer to an atomic version of Arc<Mutex<T>> or a safe and reference-counted std::sync::atomic::AtomicPtr.

Therefore, I suggest enhancing the module-level documentation of circ to clarify when to use circ::Rc and when to use circ::AtomicRc and others. Although it’s possible to determine this by thoroughly reading through the existing documentation, I believe a simplified guide would be more user-friendly. Something akin to the list format found in Rust’s standard library documentation for collections would be ideal. What are your thoughts on this suggestion?

P.S. While I think it might be worth considering renaming circ::AtomicRc, I haven’t come up with a better alternative yet.

[Lee-Janggun]

Renaming AtomicRc: AtomicPtrRc or AtomicRcPtr is more descriptive.

[simnalamburt]

I think a name that explains how users should use the type (i.e. MutableRc?), rather than a more technical name like AtomicPtrRc or AtomicRcPtr that describes its internal structure, would be more suitable.

However, for now, let’s focus more on documentation. If the documentation is well-written, users will still be able to use it even if the name is a bit unconventional.