# `ic-cdk-executor`
An async executor for [`ic-cdk`](https://docs.rs/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:
```rust
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 `inspect_message`, should use
`in_tracking_query_executor_context`.
The expected boilerplate for an inter-canister call callback looks like this:
```rust
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.