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>

class Once;

Type Aliases

Name

Description

OnceLock

Special token created by a single thread to pass to the enter, leave, and cancel methods.

Member Functions

Name

Description

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.

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).

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.

isMaybeUninitialized

Return true if this object may not be in the "done" state (that is, leave has not been called).

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

Name

Description

d_mutex

Mutex used to synchronize one‐time execution. Public for static initialization, but do not access directly.

d_state

One‐time execution state. Public for static initialization, but do not access directly.

Created with MrDocs