Struct embassy_executor::raw::Executor
source · pub struct Executor { /* private fields */ }
Expand description
Raw executor.
This is the core of the Embassy executor. It is low-level, requiring manual handling of wakeups and task polling. If you can, prefer using one of the higher level executors.
The raw executor leaves it up to you to handle wakeups and scheduling:
- To get the executor to do work, call
poll()
. This will poll all queued tasks (all tasks that “want to run”). - You must supply a pender function, as shown below. The executor will call it to notify you
it has work to do. You must arrange for
poll()
to be called as soon as possible. - Enabling
arch-xx
features will define a pender function for you. This means that you are limited to using the executors provided to you by the architecture/platform implementation. If you need a different executor, you must not enablearch-xx
features.
The pender can be called from any context: any thread, any interrupt priority
level, etc. It may be called synchronously from any Executor
method call as well.
You must deal with this correctly.
In particular, you must NOT call poll
directly from the pender callback, as this violates
the requirement for poll
to not be called reentrantly.
The pender function must be exported with the name __pender
and have the following signature:
#[export_name = "__pender"]
fn pender(context: *mut ()) {
// schedule `poll()` to be called
}
The context
argument is a piece of arbitrary data the executor will pass to the pender.
You can set the context
when calling Executor::new()
. You can use it to, for example,
differentiate between executors, or to pass a pointer to a callback that should be called.
Implementations§
source§impl Executor
impl Executor
sourcepub fn new(context: *mut ()) -> Self
pub fn new(context: *mut ()) -> Self
Create a new executor.
When the executor has work to do, it will call the pender function and pass context
to it.
See Executor
docs for details on the pender.
sourcepub unsafe fn poll(&'static self)
pub unsafe fn poll(&'static self)
Poll all queued tasks in this executor.
This loops over all tasks that are queued to be polled (i.e. they’re freshly spawned or they’ve been woken). Other tasks are not polled.
You must call poll
after receiving a call to the pender. It is OK
to call poll
even when not requested by the pender, but it wastes
energy.
§Safety
You must NOT call poll
reentrantly on the same executor.
In particular, note that poll
may call the pender synchronously. Therefore, you
must NOT directly call poll()
from the pender callback. Instead, the callback has to
somehow schedule for poll()
to be called later, at a time you know for sure there’s
no poll()
already running.