Module line_token 

Helpers for synchronizing operations (e.g. error handling) across futures.

This module revolves around the Line struct, which is an asynchronous flow control structure that behaves a bit like a mutex, with the exception that consumers waiting for the Line to be released do not subsequently lock it.

The design of a Line is inspired from the one of a one-track railway line. To avoid collisions, conductors must acquire a token at the entrance to the line that ensures they’re the only one on it. If the token is being held, traffic around this line stops until it’s released again.

Similarly, in a context with multiple parallel Futures, it might be necessary to ensure only one takes care of a given operation. For example, if multiple requests are being performed against the same service, and one of them hits an authentication error, it is likely the others will as well. In this case, it is preferrable to only let one future handle the error than let every request re-authenticate independently (in this example, credentials are the same across requests, and multiple simultaneous authentication attempts might cause issues with complex flows).

Each future holds a shared on a Line (e.g. wrapped in an Rc or an Arc). Whenever a future needs to perform an operation that should only be performed once at a time, it attempts to acquire the line’s token with Line::try_acquire_token. This function returns an enum (AcquireOutcome) describing one of two cases:

• The line’s token is available and has been acquired, and the future can start performing the operation immediately. It is granted the line’s Token, which it must hold in scope for the duration of the operation, as dropping it releases the line.
• The line’s token has already been acquired by another future, in which case the future must wait for the line to become available again. When the line becomes available again, the future does not need to acquire another token, as another future should have taken care of performing the operation.

Structs

Line

A Line from which a Token can be acquired.

Token

A token that symbolizes the current consumer holds exclusive access to the corresponding Line.

Enums

AcquireOutcome

The outcome from trying to acquire a Token for a Line.