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:

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
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:

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

Definition at line 57 of file promise.hpp.

#include <promise.hpp>

Inheritance diagram for Promise:

[legend]

Collaboration diagram for Promise:

[legend]

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 (ALIB_DBG_TAKE_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 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 64 of file promise.hpp.

Field Details:

◆ DbgFulfillCI

lang::CallerInfo 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 92 of file promise.hpp.

◆ DbgWaitCI

lang::CallerInfo 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 97 of file promise.hpp.

◆ DbgWaitTimeLimit

Ticks::Duration 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 87 of file promise.hpp.

◆ future

std::future<State> future

protected

Used for implementation.

Definition at line 78 of file promise.hpp.

◆ promise

std::promise<State> promise

protected

Used for implementation.

Definition at line 77 of file promise.hpp.

Constructor(s) / Destructor Details:

◆ Promise()

Promise ( )

inline

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

Definition at line 103 of file promise.hpp.

◆ ~Promise()

~Promise ( )

inline

Destructor.

Definition at line 113 of file promise.hpp.

Method Details:

◆ DbgOmitDestructionWarning()

void 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 125 of file promise.hpp.

◆ Fulfill()

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

inline

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.

Definition at line 142 of file promise.hpp.

◆ Wait()

State Wait ( ALIB_DBG_TAKE_CI )

inline

Waits an unlimited time for the promise to become fulfilled.

Debug Parameter:: Pass macro ALIB_CALLER_PRUNED with invocations.

Returns: The state given by the second thread with Fulfill.

Definition at line 161 of file promise.hpp.

Here is the call graph for this function:

◆ WaitFor() [1/2]

State 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 234 of file promise.hpp.

Here is the call graph for this function:

◆ WaitFor() [2/2]

State WaitFor	(	const Ticks::Duration::TDuration &	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 204 of file promise.hpp.

◆ WaitUntil()

State WaitUntil	(	const Ticks &	wakeUpTime,
		const CallerInfo &	ci )

inline

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.

Definition at line 248 of file promise.hpp.

Here is the call graph for this function:

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

promise.hpp

Description:

Public Type Index:

Public Field Index:

Public Method Index:

Protected Field Index:

Enumeration Details:

◆ State

Field Details:

◆ DbgFulfillCI

◆ DbgWaitCI

◆ DbgWaitTimeLimit

◆ future

◆ promise

Constructor(s) / Destructor Details:

◆ Promise()

◆ ~Promise()

Method Details:

◆ DbgOmitDestructionWarning()

◆ Fulfill()

◆ Wait()

◆ WaitFor() [1/2]

◆ WaitFor() [2/2]

◆ WaitUntil()