Module traits

Expand description

A series of traits to implement the behavior of reactive primitive, especially signals.

§Principles

Composition: Most of the traits are implemented as combinations of more primitive base traits, and blanket implemented for all types that implement those traits.
Fallibility: Most traits includes a try_ variant, which returns None if the method fails (e.g., if signals are arena allocated and this can’t be found, or if an RwLock is poisoned).

§Metadata Traits

DefinedAt is used for debugging in the case of errors and should be implemented for all signal types.
IsDisposed checks whether a signal is currently accessible.

§Base Traits

Trait	Mode	Description
`Track`	—	Tracks changes to this value, adding it as a source of the current reactive observer.
`Notify`	—	Notifies subscribers that this value has changed.
`ReadUntracked`	Guard	Gives immutable access to the value of this signal.
`Write`	Guard	Gives mutable access to the value of this signal.

§Derived Traits

§Access

Trait	Mode	Composition	Description
`WithUntracked`	`fn(&T) -> U`	`ReadUntracked`	Applies closure to the current value of the signal and returns result.
`With`	`fn(&T) -> U`	`ReadUntracked` + `Track`	Applies closure to the current value of the signal and returns result, with reactive tracking.
`GetUntracked`	`T`	`WithUntracked` + `Clone`	Clones the current value of the signal.
`Get`	`T`	`GetUntracked` + `Track`	Clones the current value of the signal, with reactive tracking.

§Update

Trait	Mode	Composition	Description
`UpdateUntracked`	`fn(&mut T)`	`Write`	Applies closure to the current value to update it, but doesn’t notify subscribers.
`Update`	`fn(&mut T)`	`UpdateUntracked` + `Notify`	Applies closure to the current value to update it, and notifies subscribers.
`Set`	`T`	`Update`	Sets the value to a new value, and notifies subscribers.

§Using the Traits

These traits are designed so that you can implement as few as possible, and the rest will be implemented automatically.

For example, if you have a struct for which you can implement ReadUntracked and Track, then WithUntracked and With will be implemented automatically (as will GetUntracked and Get for Clone types). But if you cannot implement ReadUntracked (because, for example, there isn’t an RwLock so you can’t wrap in a ReadGuard, but you can still implement WithUntracked and Track, the same traits will still be implemented.

Traits§

DefinedAt: Describes where the signal was defined. This is used for diagnostic warnings and is purely a debug-mode tool.
Dispose: Allows disposing an arena-allocated signal before its owner has been disposed.
FlattenOptionRefOption: Helper trait to implement flatten() on Option<&Option<T>>.
FromStream: Allows creating a signal from an async Stream.
Get: Clones the value of the signal, without tracking the value reactively. and subscribes the active reactive observer (an effect or computed) to changes in its value.
GetUntracked: Clones the value of the signal, without tracking the value reactively.
GetValue: A variation of the Get trait that provides a signposted “always-non-reactive” API. E.g. for StoredValue.
IntoInner: Turns a signal back into a raw value.
IsDisposed: Checks whether a signal has already been disposed.
Notify: Notifies subscribers of a change in this signal.
Read: Give read-only access to a signal’s value by reference through a guard type, and subscribes the active reactive observer (an effect or computed) to changes in its value.
ReadOptional: An alternative Read trait that works with Option<Readable> types.
ReadUntracked: Give read-only access to a signal’s value by reference through a guard type, without tracking the value reactively.
ReadUntrackedOptional: An alternative ReadUntracked trait that works with Option<Readable> types.
ReadValue: A variation of the Read trait that provides a signposted “always-non-reactive” API. E.g. for StoredValue.
Set: Updates the value of the signal by replacing it.
SetValue: A variation of the Set trait that provides a signposted “always-non-reactive” API. E.g. for StoredValue.
ToStream: Allows converting a signal into an async Stream.
Track: Allows tracking the value of some reactive data.
UntrackableGuard: A reactive, mutable guard that can be untracked to prevent it from notifying subscribers when it is dropped.
Update: Updates the value of a signal by applying a function that updates it in place, notifying its subscribers that the value has changed.
UpdateUntracked: Updates the value of a signal by applying a function that updates it in place, without notifying subscribers.
UpdateValue: A variation of the Update trait that provides a signposted “always-non-reactive” API. E.g. for StoredValue.
With: Give read-only access to a signal’s value by reference inside a closure, and subscribes the active reactive observer (an effect or computed) to changes in its value.
WithOptional: An alternative With trait that works with Option<Withable> types.
WithUntracked: Give read-only access to a signal’s value by reference inside a closure, without tracking the value reactively.
WithUntrackedOptional: An alternative WithUntracked trait that works with Option<Withable> types.
WithValue: A variation of the With trait that provides a signposted “always-non-reactive” API. E.g. for StoredValue.
Write: Gives mutable access to a signal’s value through a guard type. When the guard is dropped, the signal’s subscribers will be notified.
WriteValue: A variation of the Write trait that provides a signposted “always-non-reactive” API. E.g. for StoredValue.

Module traitsCopy item path