Struct stakker::Share

pub struct Share<T> { /* private fields */ }

Ref-counted shared mutable data

This allows synchronous modification of shared state from actor methods. Note that if you only wish to share immutable data between actors, it’s less verbose to simply use Rc from the standard library. Also you might wish to handle very small amounts of shared mutable data with Rc<Cell> instead.

Share is provided as a compile-time-checked zero-cost alternative to Rc<RefCell>. If Share didn’t exist, the temptation to use Rc<RefCell> occasionally would likely be too great. However Rc<RefCell> brings the risk of unexpected runtime panics. Modification of one piece of code might unexpectedly cause another distant piece of code to crash, but quite possibly only under certain conditions which makes that failure hard to anticipate in testing. In short Rc<RefCell> should be avoided wherever possible. With Share everything is checked at compile time.

Note that using Share, Rc<RefCell> or Rc<Cell> breaks the actor model. Using them to share mutable data between actors effectively causes those actors to be bound together in a group. It would be impossible to split one of those actors off to another process or over a remote link. However the actor model still applies to the group’s external interface.

So this must be used with some knowledge of the trade-offs. It could easily lead to dependency on the order of execution of actors. Treat this as similar in danger level to shared memory between threads or IPC shared memory between processes. You don’t need locking however because if you get a mutable reference to the contents you’ll have exclusive access until you give it up thanks to Rust’s borrow checker.

To borrow more than one Share instance at a time, see Core::share_rw2 and Core::share_rw3.

It’s not possible to pass a Core reference to methods on a Share item due to borrowing restrictions. If you need a Core reference, then use arguments of “this: &Share<Self>, core: &mut Core” instead of “&mut self”, and do self access via this.rw(core). (However if it’s getting this complicated, maybe consider whether the shared data should be made into an actor instead, or whether some other approach would be better.)

By default borrow-checking of access to the contents of the Share is handled at compile-time using a TCell or TLCell with its owner in Core, so it is zero-cost and compiles down to a direct pointer access to the contents of a struct, just as if the Share wasn’t there. However cloning a Share has the normal Rc overheads.

Implementations

impl<T> Share<T>

pub fn new(core: &Core, val: T) -> Self

Create a new Share instance

pub fn ro<'a>(&'a self, core: &'a Core) -> &'a T

Get a read-only (immutable, shared) reference to the contents of the Share instance. By default this is a static check, which compiles down to a direct access.

pub fn rw<'a>(&'a self, core: &'a mut Core) -> &'a mut T

Get a read-write (mutable, exclusive) reference to the contents of the Share instance. By default this is a static check, which compiles down to a direct access.

To access more than one Share instance at the same time, see Core::share_rw2 and Core::share_rw3.

pub fn downgrade(&self) -> ShareWeak<T>

Create a ShareWeak reference to the contained object

pub fn strong_count(&self) -> usize

Return the number of strong references to the shared data

pub fn weak_count(&self) -> usize

Return the number of weak references to the shared data

Trait Implementations

impl<T> Clone for Share<T>

fn clone(&self) -> Self

Return another reference to the shared data

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.