Trait Hook

pub trait Hook:
    HookPollNextUpdate
    + HookUnmount
    + for<'hook> HookValue<'hook> {
    // Required method
    fn use_hook(self: Pin<&mut Self>) -> <Self as HookValue<'_>>::Value;
}

Defines how to use a hook (get value from the hook).

A hook is something that outputs values reactively.

How to impl Hook

Usually, you don’t need to impl Hook. You can easily compose hooks with hook_fn!(...) or #[hook].

The hook fn actually returns impl UpdateHookUninitialized<Hook = impl Hook>, so that this hook fn can also be composed in other hook_fn. For more information, see hook_fn!(...).

with hook_fn!(...) macro

hook_fn![
    pub fn use_my_hook() -> &'hook mut i32 {
        let (state, updater) = h![use_shared_set(1)];
        state
    }
];

with #[hook] attribute macro

/// Print debug on `value` change.
#[hook]
fn use_debug<T: std::fmt::Debug + PartialEq + Copy>(value: T) {
    use_effect(|v: &_| {
        println!("{v:?}");
    }, value);
}

implement Hook manually.

See impl_hook!.

Comparison with LendingAsyncIterator

A Hook is like a LendingAsyncIterator. They both produce items asynchronously, but they have different meanings on pending and terminating:

For pending:

• If a LendingAsyncIterator is pending (poll_next returns Poll::Pending), it is producing the next item.

• If a Hook is pending, (poll_next_update returns Poll::Pending), it is waiting for its inner state to update. When a Hook is pending, the executor can still use it by calling use_hook and the returned value would remain the same as the last returned value. Using a hook is like inspecting it. Some hooks may do heavy work in use_hook. It is advised to call use_hook only after poll_next_update returns Poll::Ready(true).

For terminating:

• If a LendingAsyncIterator is terminated (poll_next returns Poll::Ready(None)), the executor MUST NOT call poll_next again.

• There is no termination for a Hook until dropped. When poll_next_update returns Poll::Ready(false), this means the hook is no longer dynamic (its inner state will no longer update). Thus, there is no need to call use_hook again because the returned value is expected to remain the same. But the executor can still call use_hook to re-get the value or update it with update_hook or h, and this might make the hook dynamic again.

  This behavior makes it possible to combine multiple hooks. When some hooks are no longer dynamic but other hooks depend on their returned values, the executor can still get the values from the no-longer-dynamic hooks, and pass the values to the dynamic hooks.

Also see NonLendingHook for a subset of hooks that doesn’t lend lifetimes to values, which are like AsyncIterator or Stream.

Required Methods

fn use_hook(self: Pin<&mut Self>) -> <Self as HookValue<'_>>::Value

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<H: Hook + Unpin + ?Sized> Hook for &mut H

fn use_hook(self: Pin<&mut Self>) -> <Self as HookValue<'_>>::Value

impl<H: Hook + Unpin + ?Sized> Hook for Box<H>

fn use_hook(self: Pin<&mut Self>) -> <Self as HookValue<'_>>::Value

impl<P> Hook for Pin<P>

where P: DerefMut, <P as Deref>::Target: Hook,

fn use_hook(self: Pin<&mut Self>) -> <Self as HookValue<'_>>::Value

Implementors

impl<InnerHook: Default + HookPollNextUpdate + HookUnmount, U: for<'hook> FnMutOneArg<Pin<&'hook mut InnerHook>>, I: Initialized> Hook for FnHook<InnerHook, U, I>