[#BloombergLP-bslmt-Turnstile]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bslmt.adoc[bslmt]::Turnstile
:relfileprefix: ../../
:mrdocs:

This class provides a mechanism to meter time. Using either the constructor or the `reset` method, the client specifies `rate`, indicating the number of events per second that the turnstile will allow. The client then calls `waitTurn`, which will either sleep until the next event is to occur, or return immediately if `waitTurn` was called after the next event is due. If `waitTurn` is not called until after the next event is due, the turnstile is said to be `lagging` behind, and calls to `waitTurn` will not sleep until the events have caught up with the schedule. Note that calling `waitTurn` a single time does not bring a turnstile back on schedule. For example, if a turnstile's configured frequency is one event per second, and the client is 10 seconds behind schedule, if `waitTurn` were subsequently called once per second, the turnstile will remain at 10 seconds behind schedule. The amount by which events are lagging behind the schedule can be determined via the `lagTime` method, which returns the positive number of microseconds by which the turnstile is lagging, or 0 if the turnstile is not behind schedule.

== Synopsis

Declared in `<bslmt_turnstile.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class Turnstile;
----

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslmt/Turnstile/2constructor.adoc[`Turnstile`]         [.small]#[constructor]#
| Create a turnstile object that admits clients at the specified `rate`, expressed as the number of turns per second. Optionally specify the (relative) `startTime` of the first turn. If `startTime` is not specified, the first turn may be taken immediately. Optionally specify `minTimeToCallSleep`, the shortest period of time in seconds that the `waitTurn` function will go to sleep. The behavior is undefined unless `0 < rate`.
| xref:BloombergLP/bslmt/Turnstile/lagTime.adoc[`lagTime`] 
| Return the positive number of microseconds difference between the the current time and the next turn, indicating that the turnstile is lagging behind the configured rate. Otherwise, return 0.
| xref:BloombergLP/bslmt/Turnstile/reset.adoc[`reset`] 
| Reset the rate of this turnstile to the specified `rate`, expressed as the number of turns per second. Optionally specify the (relative) `startTime` of the first turn. If `startTime` is not specified, the first turn may be taken immediately. Optionally specify `minTimeToCallSleep`, the shortest period of time in seconds that the `waitTurn` function will go to sleep. The behavior is undefined unless `0 < rate`. Note that threads blocked on `waitTurn` are not interrupted.
| xref:BloombergLP/bslmt/Turnstile/waitTurn.adoc[`waitTurn`] 
| Sleep until the next turn may be taken or return immediately if the optionally specified `sleep` is false, this turnstile is lagging behind schedule, or if the calculated sleep duration is less than `minTimeToCallSleep`. Return the non‐negative number of microseconds spent waiting, or if `sleep` is false, the number of microseconds the function would have had to wait.
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#