alib::threads::Promise Class Reference

Description:

A simple class which aggregates C++ standard library mechanics provided with std::promise and std::future into one simple interface.

The following features and facts are notable:

1. The class is not designed for multiple threads to wait on this promise to be fulfilled. Only one thread is allowed to wait.
   For other use-cases, see alternative type Condition
2. When fulfillment is acknowledged, a standardized state can be given. Besides the default state Fulfilled, two other states are built-in. Custom states can be defined and given.
   An application might agree that, for example, each thread has to stop in the case that somewhere state EmergencyStop was set. Note that some mechanics have to be implemented which ensures that such an emergency state is propagated to all relevant entities.

The class cannot be copied (just like std::promise can't be). Therefore, usually a pointer to an object is passed to the fulfilling thread and the waiting thread is responsible for ensuring the lifecycle of the object survived until the promise is fulfilled.

With debug-compilations, the field DbgWaitTimeLimit enables the raise of ALib warnings in case a certain wait time is exceeded when using the unlimited blocking method

Furthermore, two ALib warnings may be raised with destruction:

1. When the promise was not fulfilled. This warning can be silenced by setting DbgFulfillCI.Line to a positive value.
2. When the promise was not awaited. This warning can be silenced by setting DbgWaitCI.Line to a positive value.

Availability

This type is not available if the compiler-symbol ALIB_SINGLE_THREADED is set.

Definition at line 45 of file promise.inl.

Inheritance diagram for alib::threads::Promise:

Collaboration diagram for alib::threads::Promise:

Public Type Index:
enum class	State {   Unfulfilled , OK , Error , EmergencyStop ,   Custom }

Public Field Index:
lang::CallerInfo	DbgFulfillCI
lang::CallerInfo	DbgWaitCI
Ticks::Duration	DbgWaitTimeLimit = Ticks::Duration::FromAbsoluteSeconds(2)

Public Method Index:
	Promise ()
	Default constructor. Sets the state to State::Unfulfilled.
	~Promise ()
	Destructor.
void	DbgOmitDestructionWarning ()
void	Fulfill (const CallerInfo &ci, State state=State::OK)
State	Wait (const CallerInfo &ci)
State	WaitFor (const Ticks::Duration &maxWaitTimeSpan, const CallerInfo &ci)
State	WaitFor (const Ticks::Duration::TDuration &maxWaitTimeSpan, const CallerInfo &ci)
State	WaitUntil (const Ticks &wakeUpTime, const CallerInfo &ci)

Protected Field Index:
std::future< State >	future
	Used for implementation.
std::promise< State >	promise
	Used for implementation.

Enumeration Details:

State

enum class alib::threads::Promise::State

strong

Enumerates possible states. With construction, Unfulfilled is set. Error or a custom value could be used if the promise could not be fulfilled for any reason. EmergencyStop could be the right choice if the whole application should stop. But this is all up to the using code.

Enumerator
Unfulfilled	The state after construction.
OK	The default state of successful fulfillment.
Error	A default error state. (Use-case dependent.)
EmergencyStop	A state indicating that everything is to be stopped. (Use-case dependent.)
Custom	The first element defining a custom state. Further custom states with higher underlying integral values can be defined.

Definition at line 52 of file promise.inl.

Field Details:

DbgFulfillCI

lang::CallerInfo alib::threads::Promise::DbgFulfillCI

Debug-information about the first caller to Fulfill. A second (forbidden) call will be asserted with information about where the first invocation was made.

Definition at line 80 of file promise.inl.

DbgWaitCI

lang::CallerInfo alib::threads::Promise::DbgWaitCI

Debug-information about the first caller to a successful wait. A second call will be asserted with information about where the first invocation to a successful wait was made.

Definition at line 85 of file promise.inl.

DbgWaitTimeLimit

Ticks::Duration alib::threads::Promise::DbgWaitTimeLimit = Ticks::Duration::FromAbsoluteSeconds(2)

This is a threshold that causes the non-timed Wait method to raise a ALib warning in debug-builds in case a thread is blocked longer than the given duration.

To disable warnings in cases that high block times are suitable, set this value to 0. The default value is two seconds.

Definition at line 75 of file promise.inl.

future

std::future<State> alib::threads::Promise::future

protected

Used for implementation.

Definition at line 66 of file promise.inl.

promise

std::promise<State> alib::threads::Promise::promise

protected

Used for implementation.

Definition at line 65 of file promise.inl.

Constructor(s) / Destructor Details:

Promise()

alib::threads::Promise::Promise ( )

inline

Default constructor. Sets the state to State::Unfulfilled.

Definition at line 91 of file promise.inl.

~Promise()

alib::threads::Promise::~Promise ( )

inline

Destructor.

Definition at line 101 of file promise.inl.

Method Details:

DbgOmitDestructionWarning()

void alib::threads::Promise::DbgOmitDestructionWarning ( )

inline

With debug-compilations, a warning is raised on destruction, in case either Fulfill was not called or a waiting method was not called (or both). With an invocation of this method, such warnings can be omitted.
Note that the function is available in release-builds as well, but empty and optimized-out.

Definition at line 113 of file promise.inl.

Fulfill()

void alib::threads::Promise::Fulfill	(	const CallerInfo &	ci,
		State	state = State::OK )

Sets the state to State::Unfulfilled. This is to be invoked by the "fulfilling" thread which received this object, for example, as a part of a command, to signal that the promise is considered fulfilled.
A thread waiting with methods Wait, WaitUntil, or WaitFor will be woken up.

Parameters

ci	Caller information. Only available with debug-builds. Use macro ALIB_CALLER_PRUNED to pass this parameter, respectively. Use macro ALIB_CALLER_PRUNED_COMMA if state should be non-defaulted.
state	The result to set. Defaults to OK.

Wait()

State alib::threads::Promise::Wait

(

const CallerInfo &

ci

)

Waits an unlimited time for the promise to become fulfilled.

Parameters

ci	Caller information. Only available with debug-builds. Use macro ALIB_CALLER_PRUNED to pass this parameter

Returns

The state given by the second thread with Fulfill.

WaitFor() [1/2]

State alib::threads::Promise::WaitFor ( const Ticks::Duration & maxWaitTimeSpan, const CallerInfo & ci )

inline

Waits for the promise to become fulfilled, but only for a given duration.

Parameters

maxWaitTimeSpan	The maximum time to wait.
ci	Caller information. Only available with debug-builds. Use macro ALIB_COMMA_CALLER_PRUNED to pass this parameter.

Returns

Either State::Unfulfilled, or the state given by the second thread with Fulfill.

Definition at line 232 of file promise.inl.

Here is the call graph for this function:

WaitFor() [2/2]

State alib::threads::Promise::WaitFor	(	const Ticks::Duration::TDuration &	maxWaitTimeSpan,
		const CallerInfo &	ci )

Waits for the promise to become fulfilled, but only for a given duration.

Parameters

maxWaitTimeSpan	The maximum time to wait.
ci	Caller information. Only available with debug-builds. Use macro ALIB_COMMA_CALLER_PRUNED to pass this parameter.

Returns

Either State::Unfulfilled, or the state given by the second thread with Fulfill.

WaitUntil()

State alib::threads::Promise::WaitUntil	(	const Ticks &	wakeUpTime,
		const CallerInfo &	ci )

Waits for the promise to become fulfilled, but only until a given point in time.

Parameters

wakeUpTime	The point in time to wake up, even if not notified.
ci	Caller information. Only available with debug-builds. Use macro ALIB_COMMA_CALLER_PRUNED to pass this parameter.

Returns

Either State::Unfulfilled, or the state given by the second thread with Fulfill.

---

The documentation for this class was generated from the following file:

• promise.inl