Skip to main content

Signal

Struct Signal 

Source
pub struct Signal<T> { /* private fields */ }
Expand description

Cloneable observable storage with equality-deduplicated writes.

Every write that changes the value increments version and notifies observers on the writing thread (see the crate-level threading notes).

Closures passed to with, update, and modify run while the value is locked, so they must not write to the same signal. Debug builds panic, naming the signal, instead of deadlocking.

Implementations§

Source§

impl<T> Signal<T>

Source

pub fn new(value: T) -> Signal<T>

Source

pub fn named(name: impl Into<Arc<str>>, value: T) -> Signal<T>

Examples found in repository?
examples/commands.rs (lines 7-10)
6fn main() -> Result<()> {
7    let worker_status = Signal::named(
8        "worker_status",
9        "Waiting for the background worker…".to_string(),
10    );
11    let application_status = Signal::named(
12        "application_status",
13        "No application multicast received yet.".to_string(),
14    );
15    let window_status = Signal::named(
16        "window_status",
17        "No window multicast received yet.".to_string(),
18    );
19
20    let worker_handler = worker_status.clone();
21    let application_handler = application_status.clone();
22    let window_handler = window_status.clone();
23    let root = Padding::all(
24        24.0,
25        Stack::vertical()
26            .gap(12.0)
27            .alignment(Alignment::Stretch)
28            .with_child(Label::new("Typed commands"))
29            .with_child(Label::new("").text_from(worker_status))
30            .with_child(Label::new("").text_from(application_status))
31            .with_child(Label::new("").text_from(window_status))
32            .with_child(
33                Button::new("Broadcast announcement").on_press_with_ctx(|ctx| {
34                    ctx.command_sender().broadcast_application(
35                        ANNOUNCEMENT,
36                        "Hello from a widget callback".to_string(),
37                    );
38                }),
39            ),
40    );
41
42    App::new()
43        .on_command(WORK_FINISHED, move |ctx, message| {
44            worker_handler.set(format!("Worker result: {message}"));
45            ctx.set_handled();
46        })
47        .on_command(ANNOUNCEMENT, move |_, message| {
48            application_handler.set(format!("Application received: {message}"));
49        })
50        .window(
51            Window::new("Commands")
52                .on_command(ANNOUNCEMENT, move |_, message| {
53                    window_handler.set(format!("Window received: {message}"));
54                })
55                .root(root),
56        )
57        .run_with_handle(|ui| {
58            std::thread::spawn(move || {
59                // Replace this with blocking I/O or CPU work.
60                ui.send_application(WORK_FINISHED, "loaded".to_string());
61            });
62        })
63}
Source

pub fn source_id(&self) -> SourceId

Source

pub fn source_name(&self) -> Arc<str> ⓘ

Source

pub fn version(&self) -> u64

Revision counter, incremented by every write that notifies.

Source

pub fn get(&self) -> T
where T: Clone,

Clone the current value. Prefer with for large values.

Source

pub fn with<R>(&self, read: impl FnOnce(&T) -> R) -> R

Read the current value by reference without cloning it.

Source

pub fn set(&self, value: T) -> bool
where T: PartialEq,

Examples found in repository?
examples/commands.rs (line 44)
6fn main() -> Result<()> {
7    let worker_status = Signal::named(
8        "worker_status",
9        "Waiting for the background worker…".to_string(),
10    );
11    let application_status = Signal::named(
12        "application_status",
13        "No application multicast received yet.".to_string(),
14    );
15    let window_status = Signal::named(
16        "window_status",
17        "No window multicast received yet.".to_string(),
18    );
19
20    let worker_handler = worker_status.clone();
21    let application_handler = application_status.clone();
22    let window_handler = window_status.clone();
23    let root = Padding::all(
24        24.0,
25        Stack::vertical()
26            .gap(12.0)
27            .alignment(Alignment::Stretch)
28            .with_child(Label::new("Typed commands"))
29            .with_child(Label::new("").text_from(worker_status))
30            .with_child(Label::new("").text_from(application_status))
31            .with_child(Label::new("").text_from(window_status))
32            .with_child(
33                Button::new("Broadcast announcement").on_press_with_ctx(|ctx| {
34                    ctx.command_sender().broadcast_application(
35                        ANNOUNCEMENT,
36                        "Hello from a widget callback".to_string(),
37                    );
38                }),
39            ),
40    );
41
42    App::new()
43        .on_command(WORK_FINISHED, move |ctx, message| {
44            worker_handler.set(format!("Worker result: {message}"));
45            ctx.set_handled();
46        })
47        .on_command(ANNOUNCEMENT, move |_, message| {
48            application_handler.set(format!("Application received: {message}"));
49        })
50        .window(
51            Window::new("Commands")
52                .on_command(ANNOUNCEMENT, move |_, message| {
53                    window_handler.set(format!("Window received: {message}"));
54                })
55                .root(root),
56        )
57        .run_with_handle(|ui| {
58            std::thread::spawn(move || {
59                // Replace this with blocking I/O or CPU work.
60                ui.send_application(WORK_FINISHED, "loaded".to_string());
61            });
62        })
63}
Source

pub fn update(&self, update: impl FnOnce(&mut T)) -> bool
where T: Clone + PartialEq,

Mutate the value and notify if it differs from before.

This clones the value to compare it. For large values use modify, which lets the closure report the change.

Source

pub fn modify(&self, modify: impl FnOnce(&mut T) -> bool) -> bool

Mutate the value in place without cloning or comparing it.

Observers are notified only when modify returns true.

Source

pub fn mark_changed(&self)

Increment the version and notify observers without touching the value.

Use after changing state the signal cannot see, such as data behind interior mutability, or as a revision bump for values without cheap equality.

Source

pub fn subscribe(&self, observer: Observer) -> Subscription

Observe changes. Unlike Observable::subscribe, this does not require T: Clone.

Source

pub fn changed(&self) -> Changed ⓘ

A future that resolves at the next change; see Observable::changed. Unlike the trait method, this does not require T: Clone.

Source

pub fn select<U>( &self, select: impl Fn(&T) -> U + Send + Sync + 'static, ) -> Selector<Signal<T>, T, U>
where T: Clone + Send + Sync + 'static, U: Clone + PartialEq + Send + Sync + 'static,

Source

pub fn select_named<U>( &self, name: impl Into<Arc<str>>, select: impl Fn(&T) -> U + Send + Sync + 'static, ) -> Selector<Signal<T>, T, U>
where T: Clone + Send + Sync + 'static, U: Clone + PartialEq + Send + Sync + 'static,

Source§

impl<T> Signal<Arc<T>>

Source

pub fn set_arc(&self, value: Arc<T>) -> bool

Replace the shared value, deduplicating by pointer rather than by value equality. get then only clones the Arc.

Source

pub fn modify_arc(&self, modify: impl FnOnce(&mut T) -> bool) -> bool
where T: Clone,

Mutate the shared value through Arc::make_mut: in place when no reader holds the current snapshot, otherwise on a fresh copy so the snapshots readers hold stay unchanged.

Observers are notified only when modify returns true.

Trait Implementations§

Source§

impl<T> Clone for Signal<T>

Source§

fn clone(&self) -> Signal<T>

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl<T> Debug for Signal<T>
where T: Debug,

Source§

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

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

impl<T> Observable<T> for Signal<T>
where T: Clone + 'static,

Source§

fn source_id(&self) -> SourceId

Source§

fn source_name(&self) -> Arc<str> ⓘ

Source§

fn get(&self) -> T

Source§

fn read(&self, reader: &mut dyn FnMut(&T))

Call reader once with a borrow of the current value. Read more
Source§

fn value_version(&self) -> Option<u64>

A counter identifying the current value, or None if unknown. Read more
Source§

fn subscribe(&self, observer: Observer) -> Subscription

Source§

fn changed(&self) -> Changed ⓘ
where Self: Sized,

A future that resolves with the next change notification after this call. It subscribes immediately, so a change made before the first poll is not missed. It needs no particular executor.

Auto Trait Implementations§

§

impl<T> Forget for Signal<T>

§

impl<T> Freeze for Signal<T>
where Arc<SignalInner<T>>: Freeze,

§

impl<T> Move for Signal<T>

§

impl<T> RefUnwindSafe for Signal<T>
where Arc<SignalInner<T>>: RefUnwindSafe,

§

impl<T> Send for Signal<T>
where Arc<SignalInner<T>>: Send,

§

impl<T> Sync for Signal<T>
where Arc<SignalInner<T>>: Sync,

§

impl<T> Unpin for Signal<T>
where Arc<SignalInner<T>>: Unpin,

§

impl<T> UnsafeUnpin for Signal<T>
where Arc<SignalInner<T>>: UnsafeUnpin,

§

impl<T> UnwindSafe for Signal<T>
where Arc<SignalInner<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<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> Downcast for T
where T: Any,

Source§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
Source§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
Source§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
Source§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
Source§

impl<T> Downcast<T> for T

Source§

fn downcast(&self) -> &T

Source§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

Source§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send> ⓘ

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
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> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> ThemeExtension for T
where T: Any + Send + Sync,

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

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

Source§

type Error = !

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

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

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

Source§

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> Upcast<T> for T

Source§

fn upcast(&self) -> Option<&T>

Source§

impl<T> WasmNotSend for T
where T: Send,

Source§

impl<T> WasmNotSendSync for T

Source§

impl<T> WasmNotSync for T
where T: Sync,

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