Module traits

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

Principles

1. Composition: Most of the traits are implemented as combinations of more primitive base traits, and blanket implemented for all types that implement those traits.
2. 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.
• 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.