Struct ArcAction

pub struct ArcAction<I, O> { /* private fields */ }

An action runs some asynchronous code when you dispatch a new value to it, and gives you reactive access to the result.

Actions are intended for mutating or updating data, not for loading data. If you find yourself creating an action and immediately dispatching a value to it, this is probably the wrong primitive.

The arena-allocated, Copy version of an ArcAction is an Action.

async fn send_new_todo_to_api(task: String) -> usize {
    // do something...
    // return a task id
    42
}
let save_data = ArcAction::new(|task: &String| {
  // `task` is given as `&String` because its value is available in `input`
  send_new_todo_to_api(task.clone())
});

// the argument currently running
let input = save_data.input();
// the most recent returned result
let result_of_call = save_data.value();
// whether the call is pending
let pending = save_data.pending();
// how many times the action has run
// useful for reactively updating something else in response to a `dispatch` and response
let version = save_data.version();

// before we do anything
assert_eq!(input.get(), None); // no argument yet
assert_eq!(pending.get(), false); // isn't pending a response
assert_eq!(result_of_call.get(), None); // there's no "last value"
assert_eq!(version.get(), 0);

// dispatch the action
save_data.dispatch("My todo".to_string());

// when we're making the call
assert_eq!(input.get(), Some("My todo".to_string()));
assert_eq!(pending.get(), true); // is pending
assert_eq!(result_of_call.get(), None); // has not yet gotten a response


// after call has resolved
assert_eq!(input.get(), None); // input clears out after resolved
assert_eq!(pending.get(), false); // no longer pending
assert_eq!(result_of_call.get(), Some(42));
assert_eq!(version.get(), 1);

The input to the async function should always be a single value, but it can be of any type. The argument is always passed by reference to the function, because it is stored in Action::input as well.

// if there's a single argument, just use that
let action1 = ArcAction::new(|input: &String| {
    let input = input.clone();
    async move { todo!() }
});

// if there are no arguments, use the unit type `()`
let action2 = ArcAction::new(|input: &()| async { todo!() });

// if there are multiple arguments, use a tuple
let action3 = ArcAction::new(|input: &(usize, String)| async { todo!() });

Implementations

impl<I, O> ArcAction<I, O>

where I: 'static, O: 'static,

pub fn new<F, Fu>(action_fn: F) -> Self

where F: Fn(&I) -> Fu + Send + Sync + 'static, Fu: Future<Output = O> + Send + 'static, I: Send + Sync, O: Send + Sync,

Creates a new action. This is lazy: it does not run the action function until some value is dispatched.

The constructor takes a function which will create a new Future from some input data. When the action is dispatched, this action_fn will run, and the Future it returns will be spawned.

The action_fn must be Send + Sync so that the ArcAction is Send + Sync. The Future must be Send so that it can be moved across threads by the async executor as needed.

let act = ArcAction::new(|n: &u8| {
    let n = n.to_owned();
    async move { n * 2 }
});

act.dispatch(3);
assert_eq!(act.input().get(), Some(3));

// Remember that async functions already return a future if they are
// not `await`ed. You can save keystrokes by leaving out the `async move`

let act2 = Action::new(|n: &String| yell(n.to_owned()));
act2.dispatch(String::from("i'm in a doctest"));

// after it resolves
assert_eq!(act2.value().get(), Some("I'M IN A DOCTEST".to_string()));

async fn yell(n: String) -> String {
    n.to_uppercase()
}

pub fn new_with_value<F, Fu>(value: Option<O>, action_fn: F) -> Self

where F: Fn(&I) -> Fu + Send + Sync + 'static, Fu: Future<Output = O> + Send + 'static, I: Send + Sync, O: Send + Sync,

Creates a new action, initializing it with the given value.

This is lazy: it does not run the action function until some value is dispatched.

The constructor takes a function which will create a new Future from some input data. When the action is dispatched, this action_fn will run, and the Future it returns will be spawned.

The action_fn must be Send + Sync so that the ArcAction is Send + Sync. The Future must be Send so that it can be moved across threads by the async executor as needed.

pub fn clear(&self)

Clears the value of the action, setting its current value to None.

This has no other effect: i.e., it will not cancel in-flight actions, set the input, etc.

impl<I, O> ArcAction<I, O>

where I: Send + Sync + 'static, O: Send + Sync + 'static,

pub fn dispatch(&self, input: I) -> ActionAbortHandle

Calls the async function with a reference to the input type as its argument.

impl<I, O> ArcAction<I, O>

where I: 'static, O: 'static,

pub fn dispatch_local(&self, input: I) -> ActionAbortHandle

Calls the async function with a reference to the input type as its argument, ensuring that it is spawned on the current thread.

impl<I, O> ArcAction<I, O>

where I: 'static, O: 'static,

pub fn new_unsync<F, Fu>(action_fn: F) -> Self

where F: Fn(&I) -> Fu + 'static, Fu: Future<Output = O> + 'static,

Creates a new action, which will only be run on the thread in which it is created.

In all other ways, this is identical to ArcAction::new.

pub fn new_unsync_with_value<F, Fu>(value: Option<O>, action_fn: F) -> Self

where F: Fn(&I) -> Fu + 'static, Fu: Future<Output = O> + 'static,

Creates a new action that will only run on the current thread, initializing it with the given value.

In all other ways, this is identical to ArcAction::new_with_value.

impl<I, O> ArcAction<I, O>

where I: 'static, O: 'static,

pub fn version(&self) -> ArcRwSignal<usize>

The number of times the action has successfully completed.

let act = ArcAction::new(|n: &u8| {
    let n = n.to_owned();
    async move { n * 2 }
});

let version = act.version();
act.dispatch(3);
assert_eq!(version.get(), 0);

// after it resolves
assert_eq!(version.get(), 1);

pub fn input(&self) -> ArcMappedSignal<Option<I>>

The current argument that was dispatched to the async function. This value will be Some while we are waiting for it to resolve, and None after it has resolved.

let act = ArcAction::new(|n: &u8| {
    let n = n.to_owned();
    async move { n * 2 }
});

let input = act.input();
assert_eq!(input.get(), None);
act.dispatch(3);
assert_eq!(input.get(), Some(3));

// after it resolves
assert_eq!(input.get(), None);

pub fn value(&self) -> ArcMappedSignal<Option<O>>

The most recent return value of the async function. This will be None before the action has ever run successfully, and subsequently will always be Some(_), holding the old value until a new value has been received.

let act = ArcAction::new(|n: &u8| {
    let n = n.to_owned();
    async move { n * 2 }
});

let value = act.value();
assert_eq!(value.get(), None);
act.dispatch(3);
assert_eq!(value.get(), None);

// after it resolves
assert_eq!(value.get(), Some(6));
// dispatch another value, and it still holds the old value
act.dispatch(3);
assert_eq!(value.get(), Some(6));

pub fn pending(&self) -> ArcMemo<bool>

Whether the action has been dispatched and is currently waiting to resolve.

let act = ArcAction::new(|n: &u8| {
    let n = n.to_owned();
    async move { n * 2 }
});

let pending = act.pending();
assert_eq!(pending.get(), false);
act.dispatch(3);
assert_eq!(pending.get(), true);

// after it resolves
assert_eq!(pending.get(), false);

Trait Implementations

impl<I, O> Clone for ArcAction<I, O>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<I, O> DefinedAt for ArcAction<I, O>

where I: 'static, O: 'static,

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.