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()
  {
    iferr_scope;
 
    _state.Init(
      [this]() -> Result<void>
      {
        // Invoke complex multithreaded initialization code.
        return ThreadedInitialization();
      });
 
    return _object;
  }
private:
  LazyInitThreaded _state;
  MyObject* _object;
  SomeMoreData _xyz;
};

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

~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]	fn	Method (usually a lambda) to initialize something, must return Result<void>.
[in]	options	OPTIONS::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]

fn

Optional 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