Crate ic_cdk_executor 

An async executor for ic-cdk. Most users should not use this crate directly. It is useful primarily for those who are writing their own CDK or a runtime host for non-Rust languages.

Contexts

The expected boilerplate for a canister method or other entrypoint (not including callbacks) looks like this:

pub extern "C" fn function() {
    in_tracking_executor_context(|| {
        // method goes here
    });
}

The in_tracking_executor_context function permits you to call spawn_* functions. As little code as possible should exist outside the block, because in_tracking_executor_context additionally sets up the panic handler.

The above applies to update contexts. Query contexts, including canister_inspect_message, should use in_tracking_query_executor_context.

The expected boilerplate for an inter-canister call callback looks like this:

unsafe extern "C" fn callback(env: usize) {
    let method = unpack_env(env);
    in_callback_executor_context_for(method, || {
       // wake the call future
    });
}
unsafe extern "C" fn cleanup(env: usize) {
    let method = unpack_env(env);
    in_trap_recovery_context_for(method, || {
        cancel_all_tasks_attached_to_current_method();
    });
}

In async contexts, all scheduled tasks are run after the closure passed to the context function returns, but before the context function itself returns.

The method parameter must be retrieved before making inter-canister calls via the extend_current_method_context function. Calling this function from the callback instead will trap.

Protection

Tasks can be either protected or migratory. Protected tasks are attached to the method that spawned them, when awoken will not resume until that method continues, and will be canceled if the method returns before they complete. Migratory tasks are not attached to any method, and will resume in whatever method wakes them.

Structs

MethodHandle

A handle to a method context. If the function returns and all handles have been dropped, the method is considered returned.

TaskHandle

A handle to a spawned task.

Functions

cancel_all_tasks_attached_to_current_method

Cancels all tasks made with spawn_protected attached to the current method.

cancel_task

Cancels a specific task by its handle.

extend_current_method_context

Produces a handle to the current method context.

in_callback_executor_context_for

Execute an inter-canister call callback in the context of the method that made it.

in_tracking_executor_context

Execute an update function in a context that allows calling spawn_protected and spawn_migratory.

in_tracking_query_executor_context

Execute a query function in a context that allows calling spawn_protected but not spawn_migratory.

in_trap_recovery_context_for

Enters a trap/panic recovery context for calling cancel_all_tasks_attached_to_current_method in.

is_recovering_from_trap

Returns true if tasks are being canceled due to a trap or panic.

spawn_migratory

Spawns a task that can migrate between methods.

spawn_protected

Spawns a task attached to the current method.