# Trailing Cell

## Purpose
This little project is inspired by works such as `magnetic` and `evmap`, which concentrate on lock-freedom. Here I introduce some wrapper representing a sort of `Cell` that implements 'trailing state' semantics. This structure is useful in the situation you have a performance-critical data structure for which reads must be fast, but writes can be slow (perhaps they are very rare). The key here is that the state is provided by the user, and under the user's control.

For instance, I intend to use this for a game to store a `bidir-map` between client ID's of which there is a fixed amount) and player ID's (which are tied to players, like usernames).

## Usefulness

A set of connected `TcWriter<M>`s have any number (initially 0) of reading
`TcReader<T,M>` objects for any types `T` (typically the same type T).
This is particularly useful when:
 * The wrapped `T` data has the set of writers W and readers R, where W != R.
 * The speed of reads is more vital than the speed of writes.
      eg: writes are very rare.
 * It's OK if read states are slightly stale.
 
It also has with it the nice properties of:
 * Granular control of reader-synchronization events.
 * Joining and leaving of writers whenever (using `TcWriter::clone`).
 * Joining and leaving of readers whenever (using `TcWriter::add_reader`).
 * Both blocking and non-blocking write options.
 * A reader can be unwrapped to return their `T` state.

The implementation allows readers to be initialized with not only different
local states, but even initial states of different types, (so long as they
all implement `TakesMessage<M>` for the same `M` as the writer(s)). It's not
clear to me how this option might be useful, but it costs nothing to
support, so why not.

## Using It Yourself

For the writers and readers to communicate, they rely on some concept of 'message'. As such, before one can do anything, one needs to implement `trait TakesMessage` for the objects that are going to represent 'state'. This involves implementing only one function, which defines how your state object is updated when faced with a particular message.

All that remains then is to create a first writer object. All readers connected to it descend from this writer, either directly or from other writers that descend from it. These readers can then be thrown around on threads as desired, each calling whichever functions necessary, all ultimately boiling down to:
 * Synchronize with writer(s).
 * Access the inner data.

## Underlying Implementation

`TcWriter` and `TcReader` are implemented as wrappers over a `bus::Bus`, where writers act as `M` producers, and readers act as `M` consumers. However, a message from any writer arrives at all readers. Readers consume buffered messages when they call their `TcReader::update` function, and serially apply these messages to their local state (as defined by the trait).


## Examples
See `tests.rs` for more annotated examples.