Struct reactive_graph::signal::RwSignal

pub struct RwSignal<T, S = SyncStorage> { /* private fields */ }

An arena-allocated signal that can be read from or written to.

A signal is a piece of data that may change over time, and notifies other code when it has changed. This is the atomic unit of reactivity, which begins all other processes of reactive updates.

This is an arena-allocated signal, which is Copy and is disposed when its reactive Owner cleans up. For a reference-counted signal that lives as long as a reference to it is alive, see ArcRwSignal.

Core Trait Implementations

Reading the Value

• .get() clones the current value of the signal. If you call it within an effect, it will cause that effect to subscribe to the signal, and to re-run whenever the value of the signal changes.
  • .get_untracked() clones the value of the signal without reactively tracking it.
• .read() returns a guard that allows accessing the value of the signal by reference. If you call it within an effect, it will cause that effect to subscribe to the signal, and to re-run whenever the value of the signal changes.
  • .read_untracked() gives access to the current value of the signal without reactively tracking it.
• .with() allows you to reactively access the signal’s value without cloning by applying a callback function.
  • .with_untracked() allows you to access the signal’s value by applying a callback function without reactively tracking it.
• .to_stream() converts the signal to an async stream of values.

Updating the Value

• .set() sets the signal to a new value.
• .update() updates the value of the signal by applying a closure that takes a mutable reference.
• .write() returns a guard through which the signal can be mutated, and which notifies subscribers when it is dropped.

Each of these has a related _untracked() method, which updates the signal without notifying subscribers. Untracked updates are not desirable in most cases, as they cause “tearing” between the signal’s value and its observed value. If you want a non-reactive container, used StoredValue instead.

Examples

let count = ArcRwSignal::new(0);

// ✅ calling the getter clones and returns the value
//    this can be `count()` on nightly
assert_eq!(count.get(), 0);

// ✅ calling the setter sets the value
//    this can be `set_count(1)` on nightly
count.set(1);
assert_eq!(count.get(), 1);

// ❌ you could call the getter within the setter
// set_count.set(count.get() + 1);

// ✅ however it's more efficient to use .update() and mutate the value in place
count.update(|count: &mut i32| *count += 1);
assert_eq!(count.get(), 2);

// ✅ you can create "derived signals" with a Fn() -> T interface
let double_count = {
  // clone before moving into the closure because we use it below
  let count = count.clone();
  move || count.get() * 2
};
count.set(0);
assert_eq!(double_count(), 0);
count.set(1);
assert_eq!(double_count(), 2);

Implementations

impl<T> RwSignal<T>

where T: Send + Sync + 'static,

pub fn new(value: T) -> Self

Creates a new signal, taking the initial value as its argument.

impl<T, S> RwSignal<T, S>

where T: 'static, S: Storage<ArcRwSignal<T>>,

pub fn new_with_storage(value: T) -> Self

Creates a new signal with the given arena storage method.

impl<T> RwSignal<T, LocalStorage>

where T: 'static,

pub fn new_local(value: T) -> Self

Creates a new signal, taking the initial value as its argument. Unlike RwSignal::new, this pins the value to the current thread. Accessing it from any other thread will panic.

impl<T, S> RwSignal<T, S>

where T: 'static, S: Storage<ArcRwSignal<T>> + Storage<ArcReadSignal<T>>,

pub fn read_only(&self) -> ReadSignal<T, S>

Returns a read-only handle to the signal.

impl<T, S> RwSignal<T, S>

where T: 'static, S: Storage<ArcRwSignal<T>> + Storage<ArcWriteSignal<T>>,

pub fn write_only(&self) -> WriteSignal<T, S>

Returns a write-only handle to the signal.

impl<T, S> RwSignal<T, S>

where T: 'static, S: Storage<ArcRwSignal<T>> + Storage<ArcWriteSignal<T>> + Storage<ArcReadSignal<T>>,

pub fn split(&self) -> (ReadSignal<T, S>, WriteSignal<T, S>)

Splits the signal into its readable and writable halves.

pub fn unite(read: ReadSignal<T, S>, write: WriteSignal<T, S>) -> Option<Self>

Reunites the two halves of a signal. Returns None if the two signals provided were not created from the same signal.

Trait Implementations

impl<T, S> Clone for RwSignal<T, S>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T, S> Debug for RwSignal<T, S>

where S: Debug,

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

Formats the value using the given formatter.

impl<T, S> Default for RwSignal<T, S>

where T: Default + 'static, S: Storage<ArcRwSignal<T>>,

fn default() -> Self

Returns the “default value” for a type.

impl<T, S> DefinedAt for RwSignal<T, S>

fn defined_at(&self) -> Option<&'static Location<'static>>

Returns the location at which the signal was defined. This is usually simply None in release mode.

impl<'de, T, S> Deserialize<'de> for RwSignal<T, S>

where T: Send + Sync + Deserialize<'de> + 'static, S: Storage<ArcRwSignal<T>>,

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T, S> Dispose for RwSignal<T, S>

fn dispose(self)

Disposes of the signal. This:

impl<T, S> Fn() for RwSignal<T, S>

where RwSignal<T, S>: Get,

extern "rust-call" fn call(&self, _args: ()) -> Self::Output

🔬This is a nightly-only experimental API. (fn_traits)

Performs the call operation.

impl<T, S> Fn(T) for RwSignal<T, S>

where RwSignal<T, S>: Set<Value = T>,

extern "rust-call" fn call(&self, args: (T,)) -> Self::Output

🔬This is a nightly-only experimental API. (fn_traits)

Performs the call operation.

impl<T, S> FnMut() for RwSignal<T, S>

where RwSignal<T, S>: Get,

extern "rust-call" fn call_mut(&mut self, _args: ()) -> Self::Output

🔬This is a nightly-only experimental API. (fn_traits)

Performs the call operation.

impl<T, S> FnMut(T) for RwSignal<T, S>

where RwSignal<T, S>: Set<Value = T>,

extern "rust-call" fn call_mut(&mut self, args: (T,)) -> Self::Output

🔬This is a nightly-only experimental API. (fn_traits)

Performs the call operation.

impl<T, S> FnOnce() for RwSignal<T, S>

where RwSignal<T, S>: Get,

type Output = <RwSignal<T, S> as Get>::Value

The returned type after the call operator is used.

extern "rust-call" fn call_once(self, _args: ()) -> Self::Output

🔬This is a nightly-only experimental API. (fn_traits)

Performs the call operation.

impl<T, S> FnOnce(T) for RwSignal<T, S>

where RwSignal<T, S>: Set<Value = T>,

type Output = ()

The returned type after the call operator is used.

extern "rust-call" fn call_once(self, args: (T,)) -> Self::Output

🔬This is a nightly-only experimental API. (fn_traits)

Performs the call operation.

impl<'a, T> From<&'a ArcRwSignal<T>> for RwSignal<T>

where T: Send + Sync + 'static,

fn from(value: &'a ArcRwSignal<T>) -> Self

Converts to this type from the input type.

impl<T> From<ArcRwSignal<T>> for RwSignal<T>

where T: Send + Sync + 'static,

fn from(value: ArcRwSignal<T>) -> Self

Converts to this type from the input type.

impl<T> From<RwSignal<Option<T>>> for MaybeProp<T>

where T: Send + Sync,

fn from(value: RwSignal<Option<T>>) -> Self

Converts to this type from the input type.

impl<T> From<RwSignal<Option<T>, LocalStorage>> for MaybeProp<T, LocalStorage>

where T: Send + Sync,

fn from(value: RwSignal<Option<T>, LocalStorage>) -> Self

Converts to this type from the input type.

impl<T> From<RwSignal<T>> for MaybeProp<T>

where T: Send + Sync + Clone,

fn from(value: RwSignal<T>) -> Self

Converts to this type from the input type.

impl<T> From<RwSignal<T>> for MaybeSignal<T>

where T: Send + Sync,

fn from(value: RwSignal<T>) -> Self

Converts to this type from the input type.

impl<T> From<RwSignal<T>> for Signal<T>

where T: Send + Sync + 'static,

fn from(value: RwSignal<T>) -> Self

Converts to this type from the input type.

impl<T> From<RwSignal<T, LocalStorage>> for MaybeProp<T, LocalStorage>

where T: Send + Sync + Clone,

fn from(value: RwSignal<T, LocalStorage>) -> Self

Converts to this type from the input type.

impl<T> From<RwSignal<T, LocalStorage>> for MaybeSignal<T, LocalStorage>

fn from(value: RwSignal<T, LocalStorage>) -> Self

Converts to this type from the input type.

impl<T> From<RwSignal<T, LocalStorage>> for Signal<T, LocalStorage>

where T: 'static,

fn from(value: RwSignal<T, LocalStorage>) -> Self

Converts to this type from the input type.

impl<T, S> From<RwSignal<T, S>> for ArcRwSignal<T>

where T: 'static, S: Storage<ArcRwSignal<T>>,

fn from(value: RwSignal<T, S>) -> Self

Converts to this type from the input type.

impl<T, S> From<RwSignal<T, S>> for SignalSetter<T, S>

where T: Send + Sync + 'static, S: Storage<ArcRwSignal<T>> + Storage<ArcWriteSignal<T>>,

fn from(value: RwSignal<T, S>) -> Self

Converts to this type from the input type.

impl<T> FromLocal<ArcRwSignal<T>> for RwSignal<T, LocalStorage>

where T: 'static,

fn from_local(value: ArcRwSignal<T>) -> Self

Converts between the types.

impl<T, S> Hash for RwSignal<T, S>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: 'static, S> IsDisposed for RwSignal<T, S>

fn is_disposed(&self) -> bool

If true, the signal cannot be accessed without a panic.

impl<T, S> PartialEq for RwSignal<T, S>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, S> ReadUntracked for RwSignal<T, S>

where T: 'static, S: Storage<ArcRwSignal<T>>,

type Value = ReadGuard<T, Plain<T>>

The guard type that will be returned, which can be dereferenced to the value.

fn try_read_untracked(&self) -> Option<Self::Value>

Returns the guard, or None if the signal has already been disposed.

fn read_untracked(&self) -> Self::Value

Returns the guard.

impl<T, St> Serialize for RwSignal<T, St>

where T: Serialize + 'static, St: Storage<ArcRwSignal<T>>,

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<T, S> Trigger for RwSignal<T, S>

where S: Storage<ArcRwSignal<T>>,

fn trigger(&self)

Notifies subscribers of a change in this signal.

impl<T, S> Writeable for RwSignal<T, S>

where T: 'static, S: Storage<ArcRwSignal<T>>,

type Value = T

The type of the signal’s value.

fn try_write(&self) -> Option<impl UntrackableGuard<Target = Self::Value>>

Returns the guard, or None if the signal has already been disposed.

fn try_write_untracked(&self) -> Option<UntrackedWriteGuard<Self::Value>>

or None if the signal has already been disposed.

fn write(&self) -> impl UntrackableGuard<Target = Self::Value>

Returns the guard.

fn write_untracked(&self) -> impl DerefMut<Target = Self::Value>

Returns a guard that will not notify subscribers when dropped.

impl<T, S> Copy for RwSignal<T, S>

impl<T, S> Eq for RwSignal<T, S>