Added Arc::try_unique

[kvark]

While trying to implement parallel ECS processing, I stumbled upon the need to mutate Arc contents. The only existed method that allowed that was make_unique, but it has issues:

• it may clone the data as if nothing happened, where the program may just need to crash
• it forces Clone bound, which I don't have

The new try_unique allows accessing the contents mutably without Clone bound and error out if the pointer is not unique.

[rust-highfive]

r? @alexcrichton

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

[alexcrichton]

Thanks for the PR! In the past we've generally been pretty hesitant about adding inherent methods on smart pointers, however as they will shadow all other methods of the same name. In the past we've requested that extra functionality for smart pointers go as top-level functions as well.

Also, we do seem to definitely have a bit of a sprawling story for extra functionality on smart pointers, there's an interesting subset of functionality between std::rc and std::arc. I'm not sure what the best story is here for these functions, and we may want to hold off on landing new features until we've had time to reconsider the extra functionality. That being said though these are all unstable so I'm also ok landing in the interim (despite that they may change slightly).

cc @aturon, do you have thoughts on adding apis such as this?

[kvark]

@alexcrichton thanks for the info!

May I wonder why top-level functions are preferred for smart pointers instead of the member functions?

I'd be happy to use the existing functions without introducing more, but as I said there is no way to get the mutable contents at the moment without Clone bound, which I don't have.

As for the intersection, for gfx-rs we'll need some sort of abstraction over Rc/Arc in order to support single-threaded/multi-threaded resource management without extra overhead (gfx-rs/gfx#636). AFAIK, that does require HKT, but we can prepare for it now by introducing a common trait that both Rc and Arc implement.

[alexcrichton]

May I wonder why top-level functions are preferred for smart pointers instead of the member functions?

Right now if a smart pointer P defines the method foo, then it is impossible to call the method foo on a type T if you say something like:

let ptr:P<T> = ...;ptr.foo();

This is because the receiver's methods trump the Deref'd type's methods, so foo will always be dispatched to P instead of T. This can be worked around with UFCS, however, so this isn't as pressing as it was before!

[kvark]

Oh, thanks, I get this now!
In case of such a conflict, one can always do ptr.deref_mut().foo(), right?

[alexcrichton]

You can indeed! I also forgot, but you can also do (*ptr).foo() to resolve the conflict as well.

[kvark]

Just to clarify - are we waiting for me to change the methods to be global, or are we blocked by @aturon to look into it?

[aturon]

@kvark Sorry for the delay. I'm happy to add a top-level experimental APIs like this.

I'd like to suggest a single method unique that produces an Option<&mut T>. You can recover is_unique through unique().is_some().

[kvark]

@aturon Right, I only added is_unique as a private helper, with the idea that users do try_unique().is_some() if they need it.

I'll update the PR shortly. Thanks for having a look!

[kvark]

Done. Anything else I need to fix?

[alexcrichton]

@bors: r+ 39aa668

Thanks!

[bors]

⌛ Testing commit 39aa668 with merge 6a7d49e...

[bors]

💔 Test failed - auto-mac-32-opt

[kvark]

@alexcrichton but.. bors showed that my docs were incorrect. Are you sure about merging?

[alexcrichton]

No worries! I fixed them in the rollup

[kvark]

@alexcrichton thanks! My machine takes ages to build and check everything...

[lilyball]

Is there some reason this was named unique() when the corresponding std::rc function is called get_mut?

[kvark]

@kballard no, I wasn't aware of get_mut, so the unique name was a mistake (unless we want rc::unique()).

[lilyball]

There's a lot of precedent in the collection types (including slices) for a get_mut that returns an Option<&mut T>, which I believe is why I called the rc function that. And more generally, I think it's a better name.

[kvark]

@kballard I'll make a PR tonight to change it.

[lilyball]

Awesome, thanks. That's one less thing for me to try and remember (since I'm on vacation right now 😀)