Struct eyeball::SharedObservable

pub struct SharedObservable<T, L: Lock = SyncLock> { /* private fields */ }

A value whose changes will be broadcast to subscribers.

Unlike Observable, SharedObservable can be Cloned but does’t dereference to T. Because of the latter, it has regular methods to access or modify the inner value.

Async-aware locking

If you want to write-lock the inner value over a .await point, that requires an async-aware lock. You can use [new_async][Self::new_async] to create a SharedObservable<T, AsyncLock>, where most methods are async but in return locking the inner value over .await points becomes unproblematic.

Implementations

impl<T> SharedObservable<T>

pub fn new(value: T) -> Self

Create a new SharedObservable with the given initial value.

pub fn subscribe(&self) -> Subscriber<T>

Obtain a new subscriber.

Calling .next().await or .next_ref().await on the returned subscriber only resolves once the inner value has been updated again after the call to subscribe.

See subscribe_reset if you want to obtain a subscriber that immediately yields without any updates.

pub fn subscribe_reset(&self) -> Subscriber<T>

Obtain a new subscriber that immediately yields.

.subscribe_reset() is equivalent to .subscribe() with a subsequent call to .reset() on the returned subscriber.

In contrast to subscribe, calling .next().await or .next_ref().await on the returned subscriber before updating the inner value yields the current value instead of waiting. Further calls to either of the two will wait for updates.

pub fn get(&self) -> T

where T: Clone,

Get a clone of the inner value.

pub fn read(&self) -> ObservableReadGuard<'_, T>

Lock the inner with shared read access, blocking the current thread until the lock can be acquired.

While the returned read guard is alive, nobody can update the inner value. If you want to update the value based on the previous value, do not use this method because it can cause races with other clones of the same SharedObservable. Instead, call of of the update_ methods, or if that doesn’t fit your use case, call write and update the value through the write guard it returns.

pub fn try_read(&self) -> TryLockResult<ObservableReadGuard<'_, T>>

Attempts to acquire shared read access to the inner value.

See RwLocks documentation for details.

pub fn write(&self) -> ObservableWriteGuard<'_, T>

Lock the inner with exclusive write access, blocking the current thread until the lock can be acquired.

This can be used to set a new value based on the existing value. The returned write guard dereferences (immutably) to the inner type, and has associated functions to update it.

pub fn try_write(&self) -> TryLockResult<ObservableWriteGuard<'_, T>>

Attempts to acquire exclusive write access to the inner value.

See RwLocks documentation for details.

pub fn set(&self, value: T) -> T

Set the inner value to the given value, notify subscribers and return the previous value.

pub fn set_if_not_eq(&self, value: T) -> Option<T>

where T: PartialEq,

Set the inner value to the given value if it doesn’t compare equal to the existing value.

If the inner value is set, subscribers are notified and Some(previous_value) is returned. Otherwise, None is returned.

pub fn set_if_hash_not_eq(&self, value: T) -> Option<T>

where T: Hash,

Set the inner value to the given value if it has a different hash than the existing value.

If the inner value is set, subscribers are notified and Some(previous_value) is returned. Otherwise, None is returned.

pub fn take(&self) -> T

where T: Default,

Set the inner value to a Default instance of its type, notify subscribers and return the previous value.

Shorthand for observable.set(T::default()).

pub fn update(&self, f: impl FnOnce(&mut T))

Update the inner value and notify subscribers.

Note that even if the inner value is not actually changed by the closure, subscribers will be notified as if it was. Use update_if if you want to conditionally mutate the inner value.

pub fn update_if(&self, f: impl FnOnce(&mut T) -> bool)

Maybe update the inner value and notify subscribers if it changed.

The closure given to this function must return true if subscribers should be notified of a change to the inner value.

impl<T, L: Lock> SharedObservable<T, L>

pub fn observable_count(&self) -> usize

Get the number of SharedObservable clones.

This always returns at least 1 since self is included in the count.

Be careful when using this. The result is only reliable if it is exactly 1, as otherwise it could be incremented right after your call to this function, before you look at its result or do anything based on that.

pub fn subscriber_count(&self) -> usize

Get the number of subscribers.

Be careful when using this. The result can change right after your call to this function, before you look at its result or do anything based on that.

pub fn strong_count(&self) -> usize

Get the number of strong references to the inner value.

Every clone of the SharedObservable and every associated Subscriber holds a reference, so this is the sum of all clones and subscribers. This always returns at least 1 since self is included in the count.

Equivalent to ob.observable_count() + ob.subscriber_count().

Be careful when using this. The result is only reliable if it is exactly 1, as otherwise it could be incremented right after your call to this function, before you look at its result or do anything based on that.

pub fn weak_count(&self) -> usize

Get the number of weak references to the inner value.

Weak references are created using downgrade or by cloning an existing weak reference.

pub fn downgrade(&self) -> WeakObservable<T, L>

Create a new WeakObservable reference to the same inner value.

Trait Implementations

impl<T, L: Lock> Clone for SharedObservable<T, L>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T, L: Lock> Debug for SharedObservable<T, L>

where L::RwLock<ObservableState<T>>: Debug,

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

Formats the value using the given formatter.

impl<T, L> Default for SharedObservable<T, L>

where T: Default, L: Lock,

fn default() -> Self

Returns the “default value” for a type.

impl<T, L: Lock> Drop for SharedObservable<T, L>

fn drop(&mut self)

Executes the destructor for this type.