Struct async_observable::Observable

pub struct Observable<T> where
    T: Clone,  { /* private fields */ }

Wraps a value and lets you fork the value to synchronize it between tasks and threads.

Creating New Observables

There are several ways to create a new observable, altough using the new function should be the preferred way.

let mut using_new = Observable::new(0);
let mut using_from = Observable::from(0);
let mut using_into: Observable<u8> = 0.into();

Publishing New Values

Publishing a new version is done by a single call to the publish() method.

observable.publish(1);
observable.publish(2);
observable.publish(3);

Receiving Updates

let mut observable = Observable::new(0);
let mut fork = observable.fork();

observable.publish(1);
observable.publish(2);
observable.publish(3);

assert_eq!(fork.next().await, 3);

Important

Keep in mind that if you publish multiple versions directly after each other there no guarantees that all forked observables will receive every change! But as long as every observable is constently asking for changes (via next()) you are guaranteed that every observable received the latest version.

Implementations

impl<T> Observable<T> where
    T: Clone, 

pub fn new(value: T) -> Self

Create a new observable from any value.

pub fn publish(&mut self, value: T)

Store provided value and notify forks.

pub fn modify<M>(&mut self, modify: M) where
    M: FnOnce(&mut T), 

Modify the underlying value and notify forks.

pub fn modify_conditional<C, M>(&mut self, condition: C, modify: M) -> bool where
    C: FnOnce(&T) -> bool,
    M: FnOnce(&mut T), 

If the condition is met, modify the underlying value and notify forks.

Returns true if the modification was executed.

let mut observable = Observable::new(0);
let mut fork = observable.fork();

observable.modify_conditional(|i| *i == 0, |i| *i = 1); // modify
assert_eq!(fork.next().await, 1);

observable.modify_conditional(|i| *i == 0, |i| *i = 2); // doesnt modify
fork.next().await; // runs forever

pub fn fork(&self) -> Observable<T>

Create a new observable from this observable. Both will listen to the same underlying value.

let mut observable = Observable::new(0);
let mut fork = observable.fork();

fork.next().await; // runs forever!

pub fn fork_and_reset(&self) -> Observable<T>

Same as fork, but the reset causes the fork to instantly have a change available with the current state.

let mut observable = Observable::new(0);
let mut fork = observable.fork_and_reset();

assert_eq!(fork.next().await, 0);

pub fn latest(&self) -> T

Creates a clone of latest version of the observable value, without consuming the change!

let mut observable = Observable::new(0);
let mut fork = observable.fork_and_reset();

observable.publish(1);

assert_eq!(fork.latest(), 1);
assert_eq!(fork.next().await, 1);

pub async fn next(&mut self) -> T

Wait until a new version of the observable was published and return a clone of the new version.

let mut observable = Observable::new(0);
let mut fork = observable.fork_and_reset();

observable.publish(1);
assert_eq!(fork.next().await, 1);

observable.publish(2);
assert_eq!(fork.next().await, 2);

fork.next().await; // runs forever!

pub fn synchronize(&mut self) -> T

Skip any potential updates and retrieve the latest version of the observed value.

let mut observable = Observable::new(0);
let mut fork = observable.fork();

observable.publish(1);
observable.publish(2);
observable.publish(3);

assert_eq!(fork.synchronize(), 3);

fork.next().await; // runs forever!

impl<T> Observable<T> where
    T: Clone + Eq, 

pub fn publish_if_changed(&mut self, value: T) -> bool

Publish a change if the new value differs from the current one.

Returns true if a change was made.

Trait Implementations

impl<T: Clone> Clone for Observable<T> where
    T: Clone, 

fn clone(&self) -> Observable<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Observable<T> where
    T: Clone + Debug, 

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> From<T> for Observable<T> where
    T: Clone, 

fn from(value: T) -> Self

Create a new observable from any value. Same as calling new.