Struct eyeball::SharedObservable
source · pub struct SharedObservable<T, L: Lock = SyncLock> { /* private fields */ }Expand description
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 to
create a SharedObservable<T, AsyncLock>, where most methods are async
but in return locking the inner value over .await points becomes
unproblematic.
Implementations§
sourcepub fn subscribe(&self) -> Subscriber<T>
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.
sourcepub fn subscribe_reset(&self) -> Subscriber<T>
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.
sourcepub fn read(&self) -> ObservableReadGuard<'_, T>
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.
sourcepub fn try_read(&self) -> TryLockResult<ObservableReadGuard<'_, T>>
pub fn try_read(&self) -> TryLockResult<ObservableReadGuard<'_, T>>
Attempts to acquire shared read access to the inner value.
See RwLocks documentation
for details.
sourcepub fn write(&self) -> ObservableWriteGuard<'_, T>
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.
sourcepub fn try_write(&self) -> TryLockResult<ObservableWriteGuard<'_, T>>
pub fn try_write(&self) -> TryLockResult<ObservableWriteGuard<'_, T>>
Attempts to acquire exclusive write access to the inner value.
See RwLocks documentation
for details.
sourcepub fn set(&self, value: T) -> T
pub fn set(&self, value: T) -> T
Set the inner value to the given value, notify subscribers and return
the previous value.
sourcepub fn set_if_not_eq(&self, value: T) -> Option<T>where
T: PartialEq,
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.
sourcepub fn set_if_hash_not_eq(&self, value: T) -> Option<T>where
T: Hash,
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.
sourcepub fn take(&self) -> Twhere
T: Default,
pub fn take(&self) -> Twhere 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()).
sourcepub fn new_async(value: T) -> Self
Available on crate feature async-lock only.
pub fn new_async(value: T) -> Self
async-lock only.Create a new async SharedObservable with the given initial value.
sourcepub async fn subscribe(&self) -> Subscriber<T, AsyncLock>
Available on crate feature async-lock only.
pub async fn subscribe(&self) -> Subscriber<T, AsyncLock>
async-lock only.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.
sourcepub fn subscribe_reset(&self) -> Subscriber<T, AsyncLock>
Available on crate feature async-lock only.
pub fn subscribe_reset(&self) -> Subscriber<T, AsyncLock>
async-lock only.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.
sourcepub async fn get(&self) -> Twhere
T: Clone,
Available on crate feature async-lock only.
pub async fn get(&self) -> Twhere T: Clone,
async-lock only.Get a clone of the inner value.
sourcepub async fn read(&self) -> ObservableReadGuard<'_, T, AsyncLock>
Available on crate feature async-lock only.
pub async fn read(&self) -> ObservableReadGuard<'_, T, AsyncLock>
async-lock only.Read the inner value.
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.
sourcepub fn try_read(&self) -> Option<ObservableReadGuard<'_, T, AsyncLock>>
Available on crate feature async-lock only.
pub fn try_read(&self) -> Option<ObservableReadGuard<'_, T, AsyncLock>>
async-lock only.Attempts to acquire shared read access to the inner value.
If it is already locked for writing, returns None.
sourcepub async fn write(&self) -> ObservableWriteGuard<'_, T, AsyncLock>
Available on crate feature async-lock only.
pub async fn write(&self) -> ObservableWriteGuard<'_, T, AsyncLock>
async-lock only.Get a write guard to the inner value.
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.
sourcepub fn try_write(&self) -> Option<ObservableWriteGuard<'_, T, AsyncLock>>
Available on crate feature async-lock only.
pub fn try_write(&self) -> Option<ObservableWriteGuard<'_, T, AsyncLock>>
async-lock only.Attempts to acquire exclusive write access to the inner value.
If it is already locked, returns None.
sourcepub async fn set(&self, value: T) -> T
Available on crate feature async-lock only.
pub async fn set(&self, value: T) -> T
async-lock only.Set the inner value to the given value, notify subscribers and return
the previous value.
sourcepub async fn set_if_not_eq(&self, value: T) -> Option<T>where
T: PartialEq,
Available on crate feature async-lock only.
pub async fn set_if_not_eq(&self, value: T) -> Option<T>where T: PartialEq,
async-lock only.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.
sourcepub async fn set_if_hash_not_eq(&self, value: T) -> Option<T>where
T: Hash,
Available on crate feature async-lock only.
pub async fn set_if_hash_not_eq(&self, value: T) -> Option<T>where T: Hash,
async-lock only.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.
sourcepub async fn take(&self) -> Twhere
T: Default,
Available on crate feature async-lock only.
pub async fn take(&self) -> Twhere T: Default,
async-lock only.Set the inner value to a Default instance of its type, notify
subscribers and return the previous value.
Shorthand for observable.set(T::default()).
sourcepub async fn update(&self, f: impl FnOnce(&mut T))
Available on crate feature async-lock only.
pub async fn update(&self, f: impl FnOnce(&mut T))
async-lock only.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.
sourcepub fn observable_count(&self) -> usize
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.
sourcepub fn subscriber_count(&self) -> usize
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.
sourcepub fn strong_count(&self) -> usize
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.
sourcepub fn weak_count(&self) -> usize
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.
sourcepub fn downgrade(&self) -> WeakObservable<T, L>
pub fn downgrade(&self) -> WeakObservable<T, L>
Create a new WeakObservable reference to the same inner value.