Module wlan_hw_sim::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.