twizzler_driver/request/
mod.rs

1//! A system for handling requests and organizing inflight requests while waiting for responses.
2//!
3//! The general structure of this system is that software implements the [RequestDriver] trait with
4//! some struct that we'll call "the request driver" or just "the driver". The driver is then
5//! wrapped by a [Requester], which internally manages the asynchrony of talking to devices.
6//!
7//! A user of the requester can call the [Requester::submit] or [Requester::submit_for_response]
8//! functions to submit a set a requests depending on if the caller wants the responses or just
9//! wants to know if the requests succeeded. The reason this distinction is maintained is that
10//! collecting responses has an overhead. The requester interacts with the driver to submit the
11//! requests.
12//!
13//! Internally, the requester assigns IDs to requests for use in communicating with the driver.
14//! These IDs are not necessarily allocated sequentially and can only be relied upon to be unique
15//! while a given request is inflight.
16//!
17//! Once a request is completed by the driver, the driver should send the response data and ID of
18//! the request that completed back to the requester with the [Requester::finish] function. The
19//! request manager will then collate the responses for matching with the requests and any errors
20//! are tracked. Once all requests in a submitted set have been completed, that set of requests is
21//! finished and awaiting on it will return a [SubmitSummary] or a [SubmitSummaryWithResponses].
22
23mod async_ids;
24mod inflight;
25mod requester;
26mod response_info;
27mod submit;
28mod summary;
29
30#[async_trait::async_trait]
31/// A trait implemented by a particular driver that can the be used by a [requester::Requester].
32pub trait RequestDriver {
33    /// The type of a request that will be used by the SubmitRequest wrapper to submit requests to
34    /// the driver.
35    type Request: Copy + Send;
36    /// The type of a response to a request that we will use to send back to the Requester via the
37    /// [requester::Requester::finish] function.
38    type Response: Copy + Send;
39    /// The type of a submit error in case submission fails.
40    type SubmitError;
41    /// The actual submit function. The driver should perform whatever device-specific submission
42    /// procedure it needs to to submit all requests.
43    async fn submit(
44        &self,
45        reqs: &mut [SubmitRequest<Self::Request>],
46    ) -> Result<(), Self::SubmitError>;
47    /// Manually flush any internal driver submission queue.
48    fn flush(&self);
49    /// The number of IDs to have in-flight at a time.
50    const NUM_IDS: usize;
51}
52
53// TODO: drop for inflight tracker, so we can remove it to save work?
54
55pub use inflight::{InFlightFuture, InFlightFutureWithResponses};
56pub use requester::Requester;
57pub use response_info::ResponseInfo;
58pub use submit::SubmitRequest;
59pub use summary::{SubmitSummary, SubmitSummaryWithResponses};
twizzler_driver/request/mod.rs

twizzler_driver/request/
mod.rs
