chipset_device/
poll_device.rs

1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
4//! Device poll services.
5//!
6//! These services are used to allow an otherwise synchronous device to run work
7//! asynchronously. A device can register to have a poll function called
8//! whenever an associated waker is woken. The poll function is passed a context
9//! that can be used to poll futures.
10//!
11//! This provides an alternative to managing a separate asynchronous task for
12//! the device. It simplifies start/stop management (because the poll function
13//! is never called while the device is stopped), and it simplifies object
14//! lifetimes and synchronization (since the poll function is called with `&mut
15//! self`, so it has full access to the device's state).
16
17use std::task::Context;
18
19/// Implemented by devices which register themselves to be polled whenever the
20/// associated waker is called.
21pub trait PollDevice {
22    /// Poll the device for asynchronous work.
23    ///
24    /// This is called asynchronously whenever the device enters the running
25    /// state, and then whenever [`wake_by_ref`](std::task::Waker::wake_by_ref)
26    /// is called on the waker passed in `cx.waker()`.
27    ///
28    /// The device will only be polled while in the running state. If the device
29    /// is stopped, any wake events will be delayed until the device runs again.
30    fn poll_device(&mut self, cx: &mut Context<'_>);
31}