LazyInitThreaded Class Reference

#include <lazyinitthreaded.h>

Detailed Description

Helper class for multithreaded lazy initialization.

Typical usage case is a method which initializes data on first call, for example

class Sample
{
public:
Result<MyObject*> GetObject()
{
_state.Init(
[this]() -> Result<void>
{
// Invoke complex multithreaded initialization code.
return ThreadedInitialization();
});
return _object;
}
private:
LazyInitThreaded _state;
MyObject* _object;
SomeMoreData _xyz;
};
AtomicInt _state
Definition: lazyinitthreaded.h:367
#define iferr_scope
Definition: resultbase.h:1384
Definition: object.h:105

Performance note: Declaring a global LazyInitThreaded as a static member of a class will degrade its performance because the compiler will guard its access with a slow and unnecessary mutex. To avoid this move the global state outside of the class.

By default cancellation of the caller will be forwarded to the lambda passed to Init() and after a OperationCancelledError Init() will retry the initialization.

Note
To use LazyInitThreaded you have to include "job.h" too.

THREADSAFE.

Classes

class  CancellationForwarder
 

Public Types

enum class  OPTIONS : Int {
  NONE ,
  FORWARD_CANCELLATION ,
  RETRY_ON_FAILURE ,
  RETRY_ON_CANCELLATION ,
  NO_EXCLUSIVE_RESOURCE ,
  DEFAULT
}
 

Public Member Functions

enum maxon::LazyInitThreaded::OPTIONS Int MAXON_ENUM_FLAGS_CLASS (OPTIONS)
 
 ~LazyInitThreaded ()
 
template<typename FN >
MAXON_ATTRIBUTE_FORCE_INLINE auto Init (FN &&fn, OPTIONS options=OPTIONS::DEFAULT) -> decltype(fn())
 
template<typename FN = decltype(Dummy)>
void Reset (FN &&fn=Dummy)
 
Bool IsInitialized () const
 
Bool HasFailed () const
 
 operator Bool () const
 

Static Private Member Functions

static void Dummy ()
 

Private Attributes

maxon::LazyInitThreaded::CancellationForwarder MAXON_ENUM_FLAGS_CLASS
 
AtomicInt _state
 

Static Private Attributes

static const Int UNINITIALIZED
 
static const Int FAILED
 
static const Int PENDING
 
static const Int ENQUEUED
 
static const Int CHECKING
 
static const Int INITIALIZED
 
static const Int STATE_MASK
 
static const Int VALUE_MASK
 

Member Enumeration Documentation

◆ OPTIONS

enum OPTIONS : Int
strong
Enumerator
NONE 
FORWARD_CANCELLATION 

Cancellation of the calling job will be forwarded.

RETRY_ON_FAILURE 

Retry initialization if it failed the first time.

RETRY_ON_CANCELLATION 

Retry initialization if it failed due to thread cancellation (OperationCancelledError). This is a special case of RETRY_ON_FAILURE.

NO_EXCLUSIVE_RESOURCE 

support cancellation etc. but do not span an exclusive resource around the lazy init threaded and all its sub-jobs

DEFAULT 

Default behaviour: Cancellation of the calling job will be forwarded, initialization will be retried if it failed due to OperationCancelledError.

Constructor & Destructor Documentation

◆ ~LazyInitThreaded()

Member Function Documentation

◆ Dummy()

static void Dummy ( )
staticprivate

◆ MAXON_ENUM_FLAGS_CLASS()

enum maxon::LazyInitThreaded::OPTIONS Int MAXON_ENUM_FLAGS_CLASS ( OPTIONS  )

◆ Init()

MAXON_ATTRIBUTE_FORCE_INLINE auto Init ( FN &&  fn,
OPTIONS  options = OPTIONS::DEFAULT 
) -> decltype(fn())

Initializes an object by calling the specified method (and does nothing if the object has already been initialized). The method #fnwill be executed by a job and is free to execute long running multithreaded code for initialization. Waiting threads will either participate in the initialization or go to sleep. They will not idle unnecessarily. If the initialization failed once and #retryOnFailure was false (the default) all following Init() calls will return the initial error. THREADSAFE.

Parameters
[in]fnMethod (usually a lambda) to initialize something, must return Result<void>.
[in]optionsOPTIONS::FORWARD_CANCELLATION by default.
Returns
True/OK if initialization was successful or object has already been initialized, otherwise result of failed initialization.

◆ Reset()

void Reset ( FN &&  fn = Dummy)

Resets an object by calling the specified method. Does nothing if the object has already been reset. If the initialization failed the optional reset method won't be invoked. THREADSAFE.

Parameters
[in]fnOptional method (usually a lambda) to reset something.

◆ IsInitialized()

Bool IsInitialized ( ) const

Returns if the object already has been initialized. THREADSAFE.

Returns
True if initialization was successful.

◆ HasFailed()

Bool HasFailed ( ) const

◆ operator Bool()

operator Bool ( ) const
explicit

Returns if the object already has been initialized. THREADSAFE.

Returns
True if initialization was successful.

Member Data Documentation

◆ UNINITIALIZED

const Int UNINITIALIZED
staticprivate

◆ FAILED

const Int FAILED
staticprivate

◆ PENDING

const Int PENDING
staticprivate

◆ ENQUEUED

const Int ENQUEUED
staticprivate

◆ CHECKING

const Int CHECKING
staticprivate

◆ INITIALIZED

const Int INITIALIZED
staticprivate

◆ STATE_MASK

const Int STATE_MASK
staticprivate

◆ VALUE_MASK

const Int VALUE_MASK
staticprivate

◆ MAXON_ENUM_FLAGS_CLASS

maxon::LazyInitThreaded::CancellationForwarder MAXON_ENUM_FLAGS_CLASS
private

◆ _state

AtomicInt _state
private