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

Gate‐keeper class for code that should only execute once per process. This class is a POD‐type and can be statically initialized to the value of the `BSLMT_ONCE_INITIALIZE` macro. For this reason, it does not have any explicitly‐declared constructors or destructor.

== Synopsis

Declared in `<bslmt_once.h>`

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

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslmt/Once/OnceLock.adoc[`OnceLock`] 
| Special token created by a single thread to pass to the `enter`, `leave`, and `cancel` methods.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslmt/Once/callOnce-02.adoc[`callOnce`] 
| If no other thread has yet called `enter` or `callOnce`, then call the specified `function` and set this object to the state where pending and future calls to `enter` or `callOnce` will return `false` or do nothing, respectively. Otherwise, wait for the one‐time code to complete and return without calling `function` where `function` is a function or functor that can be called with no arguments. Note that one‐time code is considered not to have run if `function` terminates with an exception.
| xref:BloombergLP/bslmt/Once/cancel.adoc[`cancel`] 
| Revert this object to the state it was in before `enter` or `callOnce` was called, then unlock the internal mutex using the specified `onceLock` (possibly unblocking pending calls to `enter` or `callOnce`). This method may only be used to cancel execution of one‐time code that has not yet completed. The behavior is undefined unless `onceLock` was locked by a matching call to `enter` on this object and has not been tampered‐with since (especially by calling `leave`).
| xref:BloombergLP/bslmt/Once/enter.adoc[`enter`] 
| Lock the internal mutex using the specified `onceLock` (possibly blocking if another thread has already locked the mutex). If no other thread has yet called `enter` or `callOnce` on this object, return `true`. Otherwise, unlock the mutex and return `false`. The mutex lock may be skipped if it can be determined that it will not be needed. The behavior is undefined if `onceLock` is already in a locked state on entry to this method. Note that if `enter` returns `true`, the caller _must_ eventually call `leave`, or else other threads may block indefinitely.
| xref:BloombergLP/bslmt/Once/isMaybeUninitialized.adoc[`isMaybeUninitialized`] 
| Return `true` if this object may not be in the "done" state (that is, `leave` has not been called).
| xref:BloombergLP/bslmt/Once/leave.adoc[`leave`] 
| Set this object into a state such that pending and future calls to `enter` or `callOnce` will return `false` or do nothing, respectively, then unlock the internal mutex using the specified `onceLock` (possibly unblocking pending calls to `enter` or `callOnce`). The behavior is undefined unless `onceLock` was locked by a matching call to `enter` on this object and has not been tampered‐with since.
|===


== Data Members

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslmt/Once/d_mutex.adoc[`d_mutex`] 
| Mutex used to synchronize one‐time execution. Public for static initialization, but do _not_ access directly.
| xref:BloombergLP/bslmt/Once/d_state.adoc[`d_state`] 
| One‐time execution state. Public for static initialization, but do _not_ access directly.
|===



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