Crate slotpoller 

This library implements a collection of pollable futures via a backing array. It has the following properties:

1. Futures can be stored on the stack.
2. The number of futures is bounded.
3. Futures are only polled when they generate wake-ups.

The API reflects these properties. There are three main structs, StackSlots, HeapSlots, and SlotPoller.

Stack slots

Using StackSlots requires you to pin it:

use std::pin::pin;
use slotpoller::{SlotPoller, StackSlots};

let stack_slots = pin!(StackSlots::<30, _>::default());
let mut slot_poller = SlotPoller::new(stack_slots);

Heap slots

HeapSlots lets you set the capacity at runtime. A capacity must be provided:

use std::num::NonZeroU16;
use slotpoller::{HeapSlots, SlotPoller};

let capacity = NonZeroU16::new(50).unwrap();
let mut slot_poller = SlotPoller::new(HeapSlots::with_capacity(capacity));

Basic Usage

After construction, most methods can be found on the SlotPoller struct.

use std::io;
use std::pin::pin;
use slotpoller::{StackSlots, SlotPoller};

async fn exec() -> Result<String, io::Error> {
  Ok(String::new())
}

async fn exec_multiple() -> Result<(), io::Error> {
  let stack_slots = pin!(StackSlots::<20, _>::default());
  let mut slot_poller = SlotPoller::new(stack_slots);

  for _ in 0..50 {
    let (res, vacancy) = slot_poller.next_vacancy().await;
    if let Some(Err(e)) = res {
      return Err(e);
    }
    vacancy.insert(exec());
  }

  slot_poller.try_drain(|res| { res?; Ok(()) }).await
}

Allocation

The allocation footprint of this crate is very minimal and stays constant over the lifetime of the poller. Here are the allocating functions in this crate:

• HeapSlots::with_capacity (2 allocations)
• StackSlots::new (1 allocation)

By design, the Rust async model requires either heap allocation or static mutable memory in order to implement wakers. Users who want an alloc-free solution (using static mutable memory) should look at the embassy-executor crate.

Panics

Functions in this library should never generate a panic, with one exception: polling a future after it has completed (see Future::poll).

Structs

DrainFuture

The future returned from SlotPoller::drain.

HeapSlots

Allocates the space for the futures on the heap.

NextCompletionFuture

The future returned from SlotPoller::next_completion.

NextVacancyFuture

The future returned from SlotPoller::next_vacancy

SlotPoller

The main poller

StackSlots

Stack-friendly memory that can be used by the poller.

TryDrainFuture

The future returned from SlotPoller::try_drain.

TryPushErr

The error produced from SlotPoller::try_push, containing the future which wasn’t pushed.

Vacancy

An open slot inside the stack poller.

Traits

SlotMemory

An internal trait, used to identify different memory providers.