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

Gate&hyphen;keeper class for code that should only execute once per process&period; This class is a POD&hyphen;type and can be statically initialized to the value of the `BSLMT&lowbar;ONCE&lowbar;INITIALIZE` macro&period; For this reason, it does not have any explicitly&hyphen;declared constructors or destructor&period;

== Synopsis

Declared in `&lt;bslmt&lowbar;once&period;h&gt;`

[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&period;
|===


== 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&period; Otherwise, wait for the one&hyphen;time code to complete and return without calling `function` where `function` is a function or functor that can be called with no arguments&period; Note that one&hyphen;time code is considered not to have run if `function` terminates with an exception&period;
| 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`)&period; This method may only be used to cancel execution of one&hyphen;time code that has not yet completed&period; The behavior is undefined unless `onceLock` was locked by a matching call to `enter` on this object and has not been tampered&hyphen;with since (especially by calling `leave`)&period;
| 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)&period; If no other thread has yet called `enter` or `callOnce` on this object, return `true`&period; Otherwise, unlock the mutex and return `false`&period; The mutex lock may be skipped if it can be determined that it will not be needed&period; The behavior is undefined if `onceLock` is already in a locked state on entry to this method&period; Note that if `enter` returns `true`, the caller _must_ eventually call `leave`, or else other threads may block indefinitely&period;
| xref:BloombergLP/bslmt/Once/isMaybeUninitialized.adoc[`isMaybeUninitialized`] 
| Return `true` if this object may not be in the &quot;done&quot; state (that is, `leave` has not been called)&period;
| 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`)&period; The behavior is undefined unless `onceLock` was locked by a matching call to `enter` on this object and has not been tampered&hyphen;with since&period;
|===


== Data Members

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



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