Crate futures_turnstyle

Turnstyles are a way to provide futures-aware gated access in a sequential fashion.

Callers will "join" the queue, and receive a future that will complete once they make it through the turnstyle. The turnstyle is controlled externally by some coordinator, and can "turn" it to let the next waiter in line through. Thus, you can have multiple waiters, which can join the line at any time, and allow the coordinator to continually admit them through.

This can be used to synchronize access to a resource, or to provide a synchronization point to repeatedly calculation.

One example is a network daemon that reloads its configuration and reestablishes all of its listening sockets. Normally, you might join (using select) both the listening socket future and a close future so that you can shutdown the socket when its no longer required.

With a turnstyle, you can join the queue every time you reload the configuration, and then share that future to all of the newly created listeners. Once the new listeners are ready, you also do one turn on the turnstyle, which signals the last waiter in line -- a future shared with all of the old listeners -- that they can now shutdown. That same turnstyle can perform this over and over without issue.

Turnstyles internally protect themselves via a Mutex but are fast enough in normal cases that you can join or turn from within a future without fear of stalling the executor. If you're joining at an extremely high frequency, you could potentially cause performance degradation.

Structs

Turnstyle	An ordered queue of waiting participants.
Waiter	A future that waits to be notified, based on its place in line.