Module request

A system for handling requests and organizing inflight requests while waiting for responses.

The general structure of this system is that software implements the RequestDriver trait with some struct that we’ll call “the request driver” or just “the driver”. The driver is then wrapped by a Requester, which internally manages the asynchrony of talking to devices.

A user of the requester can call the Requester::submit or Requester::submit_for_response functions to submit a set a requests depending on if the caller wants the responses or just wants to know if the requests succeeded. The reason this distinction is maintained is that collecting responses has an overhead. The requester interacts with the driver to submit the requests.

Internally, the requester assigns IDs to requests for use in communicating with the driver. These IDs are not necessarily allocated sequentially and can only be relied upon to be unique while a given request is inflight.

Once a request is completed by the driver, the driver should send the response data and ID of the request that completed back to the requester with the Requester::finish function. The request manager will then collate the responses for matching with the requests and any errors are tracked. Once all requests in a submitted set have been completed, that set of requests is finished and awaiting on it will return a SubmitSummary or a SubmitSummaryWithResponses.

Structs

InFlightFuture

A future for a set of in-flight requests for which we are uninterested in any responses from the device, we only care if the responses were completed successfully or not. On await, returns a SubmitSummary.

InFlightFutureWithResponses

A future for a set of in-flight requests for which we are interested in all responses from the device. On await, returns a SubmitSummaryWithResponses.

Requester

A wrapper for managing requests and responses for a given driver.

ResponseInfo

Information about a response from the driver. Sent by the driver back to the request manager.

SubmitRequest

A wrapper around a request that adds an ID alongside a request. The ID is automatically allocated internally by the request manager after the SubmitRequest is submitted.

Enums

SubmitSummary

A summary of the result of submitting a collection of requests to the request manager and having the device respond. Does not contain responses.

SubmitSummaryWithResponses

A summary of the result of submitting a collection of requests to the request manager and having the device respond. Contains responses.

Traits

RequestDriver

A trait implemented by a particular driver that can the be used by a requester::Requester.