Struct Executor

pub struct Executor { /* private fields */ }

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 enable arch-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

impl Executor

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.

pub unsafe fn initialize(&'static self)

Initializes the executor.

Safety

This function must be called once before any other method is called.

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 call initialize before calling this method.

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.

pub fn spawner(&'static self) -> Spawner

Get a spawner that spawns tasks in this executor.

It is OK to call this method multiple times to obtain multiple Spawners. You may also copy Spawners.