Struct eyeball::Observable

source ·
pub struct Observable<T, L: Lock = SyncLock> { /* private fields */ }
Expand description

A value whose changes will be broadcast to subscribers.

Observable<T> dereferences to T, and does not have methods of its own to not clash with methods of the inner type. Instead, to interact with the Observable itself rather than the inner value, use its associated functions (e.g. Observable::subscribe(observable)).

§Async-aware locking

Contrary to SharedObservable’s async-aware locking support, using Observable with L = [AsyncLock] with this type is rarely useful since having access to the Observable means nobody can be mutating the inner value in parallel. It allows a subscriber to read-lock the value over a .await point without losing Send-ness of the future though.

Implementations§

source§

impl<T> Observable<T>

source

pub fn new(value: T) -> Self

Create a new Observable with the given initial value.

source

pub fn subscribe(this: &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.

source

pub fn subscribe_reset(this: &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.

source

pub fn get(this: &Self) -> &T

Get a reference to the inner value.

Usually, you don’t need to call this function since Observable<T> implements Deref. Use this if you want to pass the inner value to a generic function where the compiler can’t infer that you want to have the Observable dereferenced otherwise.

source

pub fn set(this: &mut Self, value: T) -> T

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

source

pub fn set_if_not_eq(this: &mut 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.

source

pub fn set_if_hash_not_eq(this: &mut 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.

source

pub fn take(this: &mut 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(this, T::default()).

source

pub fn update(this: &mut 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.

source

pub fn update_if(this: &mut 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.

source§

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

source

pub fn subscriber_count(this: &Self) -> usize

Get the number of subscribers.

Be careful when using this. The result is only reliable if it is exactly 0, 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.

source

pub fn into_shared(this: Self) -> SharedObservable<T, L>

Convert this unique Observable into a SharedObservable.

Any subscribers created for self remain valid.

Trait Implementations§

source§

impl<T, L: Lock> Debug for Observable<T, L>
where L::Shared<ObservableState<T>>: Debug,

source§

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

Formats the value using the given formatter. Read more
source§

impl<T, L> Default for Observable<T, L>
where T: Default, L: Lock,

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

impl<T> Deref for Observable<T>

§

type Target = T

The resulting type after dereferencing.
source§

fn deref(&self) -> &Self::Target

Dereferences the value.
source§

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

source§

fn drop(&mut self)

Executes the destructor for this type. Read more

Auto Trait Implementations§

§

impl<T, L> Freeze for Observable<T, L>
where <L as Lock>::Shared<ObservableState<T>>: Freeze,

§

impl<T, L> RefUnwindSafe for Observable<T, L>
where <L as Lock>::Shared<ObservableState<T>>: RefUnwindSafe,

§

impl<T, L> Send for Observable<T, L>
where <L as Lock>::Shared<ObservableState<T>>: Send,

§

impl<T, L> Sync for Observable<T, L>
where <L as Lock>::Shared<ObservableState<T>>: Sync,

§

impl<T, L> Unpin for Observable<T, L>
where <L as Lock>::Shared<ObservableState<T>>: Unpin,

§

impl<T, L> UnwindSafe for Observable<T, L>
where <L as Lock>::Shared<ObservableState<T>>: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more