Add is_unique(), try_unwrap(), get_mut() to alloc::rc

[lilyball]

Add a few new free functions to alloc::rc for manipulating
uniquely-owned Rc values. is_unique() can be used to test if the Rc is
uniquely-owned, try_unwrap() can remove the value from a uniquely-owned
Rc, and get_mut() can return a &mut for a uniquely-owned Rc.

These are all free functions, because smart pointers should avoid having
methods when possible. They can't be static methods because UFCS will
remove that distinction. I think we should probably change downgrade()
and make_unique() into free functions as well, but that's out of scope.

[emberian]

I think this is useful and want it. PR looks good, will let someone else r+

[alexcrichton]

This and the above example use Rc.foo which probably needs to get re-jiggered to rc::foo.

[lilyball]

You're right, I guess I never ran the doc tests after changing to free functions.

[emberian]

@aturon Possibly doesn't make a lot of sense out of context:
gfx-rs/gfx#144 (comment)

Essentially you want an affine handle type that, for performance reasons,
can't really have a useful destructor, and the only way to share it is
behind Rc (or another shared container), but in the interest of not
having referring to values that no longer exist, removing the value from
the container requires the handle by-value, but you can't get that without
try_unwrap. It moves the failure into the user who is sharing the handle,
rather than having a handle which refers to a nonexistent value.

On Wed, Jul 30, 2014 at 10:04 AM, Kevin Ballard notifications@github.com
wrote:

In src/liballoc/rc.rs:

• }
  +}

+/// Returns a mutable reference to the contained value if the Rc has
+/// unique ownership.
+///
+/// Returns None if the Rc does not have unique ownership.
+///
+/// # Example:
+///
+/// ```
+/// let mut x = Rc::new(3u);
+/// _Rc.try_get_mut(&mut x).unwrap() = 4u;
+/// assert_eq!(_x, 4u);
+/// let _y = x.clone();
+/// assert!(Rc.try_get_mut(&mut x).is_none());

You're right, I guess I never ran the doc tests after changing to free
functions.

—
Reply to this email directly or view it on GitHub
https://github.com/rust-lang/rust/pull/16101/files#r15597313.

http://octayn.net/

[emberian]

(The performance reasons being size, it would make the handle 4x larger, 4
bytes vs 16, https://gist.github.com/cmr/d7dca23f0d888ac5d19d, and these
handles are how users refer to almost every object in the API)

On Wed, Jul 30, 2014 at 11:29 AM, Corey Richardson corey@octayn.net wrote:

@aturon Possibly doesn't make a lot of sense out of context:
gfx-rs/gfx#144 (comment)

Essentially you want an affine handle type that, for performance reasons,
can't really have a useful destructor, and the only way to share it is
behind Rc (or another shared container), but in the interest of not
having referring to values that no longer exist, removing the value from
the container requires the handle by-value, but you can't get that without
try_unwrap. It moves the failure into the user who is sharing the handle,
rather than having a handle which refers to a nonexistent value.

On Wed, Jul 30, 2014 at 10:04 AM, Kevin Ballard notifications@github.com
wrote:

In src/liballoc/rc.rs:

• }
  +}

+/// Returns a mutable reference to the contained value if the Rc has
+/// unique ownership.
+///
+/// Returns None if the Rc does not have unique ownership.
+///
+/// # Example:
+///
+/// ```
+/// let mut x = Rc::new(3u);
+/// _Rc.try_get_mut(&mut x).unwrap() = 4u;
+/// assert_eq!(_x, 4u);
+/// let _y = x.clone();
+/// assert!(Rc.try_get_mut(&mut x).is_none());

You're right, I guess I never ran the doc tests after changing to free
functions.

—
Reply to this email directly or view it on GitHub
https://github.com/rust-lang/rust/pull/16101/files#r15597313.

http://octayn.net/

http://octayn.net/

[aturon]

@cmr I'd be interested to hear about the use case you have in mind.

[lilyball]

Fixed the doc comment examples.

[aturon]

@cmr So, the gist seems to be that you have some other mechanism telling you that the Rc should be uniquely owned at some point, and hence try_unwrap should always succeed?

[emberian]

@aturon Yes, but only dynamically, up to the application...

[emberian]

Also the comment I left explaining the situation seems to have been eaten by github... looking for it in my sent emails.

[emberian]

@aturon Possibly doesn't make a lot of sense out of context: gfx-rs/gfx#144 (comment)

Essentially you want an affine handle type that, for performance reasons, can't really have a useful destructor, and the only way to share it is behind Rc (or another shared container), but in the interest of not having referring to values that no longer exist, removing the value from the container requires the handle by-value, but you can't get that without try_unwrap. It moves the failure into the user who is sharing the handle, rather than having a handle which refers to a nonexistent value.

[lilyball]

@cmr The comment you left was actually a reply to a diff comment, so it's hidden on an outdated diff.

[emberian]

Ah, yay github.

[aturon]

FWIW, I'm fine with adding these as "experimental", which they've been marked.

One nit: the current error guidelines, which represent our current best practices, prefer to avoid try_foo when foo returns an Option/Result. (We use names like Vec::pop instead of Vec::try_pop, for example.)

[lilyball]

@aturon try_unwrap() doesn't make any sense as unwrap(), there's no precedent for a method of that name returning an Option/Result (existing precedent implies it would fail if it can't return the T). But perhaps try_get_mut() does warrant changing to just get_mut().

[lilyball]

Updated. try_get_mut() is now get_mut().

[aturon]

OK, I'm fine with try_unwrap for now, though this is likely to change with the resolution of the unwrap conventions.