Module event

Event handling and composition for interacting with the WLAN tap driver.

This module provides APIs for writing tests that must handle and interact with events from the WLAN tap driver. The primary mechanism for this are event handlers, which can be composed in sophisticated ways to route and act upon events. The hardware simulator test harness forwards events into these handlers.

Event handlers are described by the Handler trait. Much like the standard Iterator trait, Handler is composable. Event handlers are constructed by composing Handlers together via combinators. Handler has many associated functions that are analogous to those found in Iterator, Option, and Result and follows many of the same patterns. The execution of handlers and routing of events is largely controlled by whether or not handlers match an event: see Handled, which resembles Option.

The primary method of the Handler trait is call, which accepts an exclusive reference to state and a shared reference to an event and must react to this event and return a Handled that describes whether or not the event was matched and, if so, what the output is.

Examples

Handler combinators can be used to construct complex event handlers in a declarative way. The following non-trivial example constructs an event handler that examines the status code of an association response frame. The handler also enforces ordering: action frames may arrive at any time, but any other management frame must follow the association response frame.

let mut handler = event::on_transmit(branch::or(( // Only handle transmit events.
    event::extract(|_: Buffered<ActionFrame<false>>| {}), // Allow (ignore) action frames...
    event::until_first_match(branch::or(( // ...or match only once.
        event::extract(|frame: Buffered<AssocRespFrame>| { // Examine response frames...
            let frame = frame.get();
            assert_eq!(
                { frame.assoc_resp_hdr.status_code },
                fidl_ieee80211::StatusCode::Success.into(),
            );
        })
        .and(event::once(|_, _| sender.send(()).unwrap())), // ...and send a completion signal...
        event::extract(|_: Buffered<MgmtFrame>| {
            panic!("unexpected management frame"); // ...or panic if a management frame arrives instead.
        }),
    ))),
)));

See existing tests for more examples of constructing event handlers.

Re-exports

pub use crate::event::Handled::Matched;

pub use crate::event::Handled::Unmatched;

Modules

action

Configurable and common handlers that act on PHYs in response to events.

branch

Chaining branch combinators.

buffered

Buffered (owned) frames and MAC data.

Structs

And

AndThen

ByRef

Context

Expect

ExpectMatchesTimes

Map

Or

StartMacArgs

Stateful

A marker type that indicates that an extractor’s first parameter accepts handler state.

TryAnd

TryAndThen

TryOr

TryOrUnmatched

Enums

Handled

The reaction of an event handler to a particular event.

Traits

Handler

A composable event handler.

Try

Divergent (fallible) types.

Functions

boxed

Boxes an event handler as a trait object.

extract

Constructs an extractor event handler that runs and matches when its parameters can be extracted from an event.

extract_and_match

Constructs an extractor event handler that runs when its parameters can be extracted from an event.

map_state

Maps the state passed to the constructed handler and forwards the mapped state to its composed handler.

matched

Constructs an event handler that always matches.

on_join_bss

Filters WlantapPhyEvents to JoinBssArgs.

on_scan

Filters WlantapPhyEvents to StartScanArgs.

on_set_channel

Filters WlantapPhyEvents to SetChannelArgs.

on_set_country

Filters WlantapPhyEvents to SetCountryArgs.

on_start_mac

Filters WlantapPhyEvents to StartMacArgs.

on_transmit

Filters WlantapPhyEvents to TxArgs.

once

Constructs an event handler from a FnOnce that only executes once.

until_first_match

Stops executing its composed handler after its first match.

with_state

Forwards the given state to the composed event handler.