Should the cow documentation mention arc?

#1

I was looking for a copy-on-write reference counted pointer. I started by reading the documentation for cow, which is almost what I want but not reference counted. When it didn't do everything I wanted (reference counting), I went looking on cargo.

I eventually found out arc, with make_mut, does what I want! But I found it hard to find this out via docs.

(Further, is this the best place to discuss doc suggestions?)

2 Likes
#2

I would discuss docs changes/improvements on internals.rust-lang.org, but here is fine too.

It would be nice to have a link to Rc::make_mut/Arc::make_mut in Cow since they can be used in similar ways.

2 Likes
#3

Copy-on-Write and reference counting are two orthogonal concepts. I don't understand why Cow's docs should refer to something that is completely distinct from Cow. You can wrap anything in an Rc or Arc, and you can wrap anything with an owned representation into a Cow, and you can even wrap one inside another or vice versa. Just because this is possible doesn't mean that the docs of Cow or Rc or Arc should mention any potential type you can use them with.

If you are looking something specific, you can go to https://doc.rust-lang.org/std, where all the modules of the standard library have a short description. If you search for "reference count" there, you'll find the rc module.

2 Likes
#4

The potential reason to mention them isnā€™t that they can be used together, itā€™s that Arc::make_mut() is an alternative way to get Clone-on-write semantics, and Cow is usually going to be the first thing people find when searching for a way to do that.

Anecdotally, I almost always end up using make_mut instead of Cow for this, but I wouldnā€™t presume that my experience is necessarily typical.

5 Likes
#5

Given that Arc::make_mut refers to its own behavior as clone-on-write, your orthogonality argument doesn't quite work.

If there are other Arc or Weak pointers to the same allocation, then make_mut will create a new allocation and invoke clone on the inner value to ensure unique ownership. This is also referred to as clone-on-write.

(Emphasis mine)

1 Like
#6

Oh, it works just fine ā€“ it's about the principle, not a particular implementation.

Arc::make_mut apparently fails the orthogonality check in this case, however, that's not a problem because it's useful and has an implementation that is efficient and (hopefully) correct but also complex, so it shouldn't be omitted.

#7

I see, that does make sense.

#8

@ChrisJefferson does something like this seem appropriate?

6 Likes
#9

That patch looks great, it's exactly what I would have wanted to see, so hopefully it will help others in future!

#10

How did you find Cow? Did you use the integrated documentation search? If you did, what did you enter? Did the get_mut methods of Rc/Arc not appear? I read about a new doc feature, that allowed attaching alternative search terms on items, so they appear when searching for them, as well. That sounds like something, that could be appropriate here, depending on your answer.

#11

I suppose if you Google ā€œrust copy on writeā€, the first result is the documentation of Cow.

#12

Yes, googling "copy on write rust" is what I started with, and I looked through Google's first few pages and didnt find mention of arc. I realise Rust wouldn't want to start tuning documentation to make Google happy, but I feel cow might be a special case as it is both a general concept and a type.

1 Like