Contains definitions for promise stores, promises and functions to manipulate them. More...

#include "uevloop/config.h"
#include "uevloop/utils/closure.h"
#include "uevloop/utils/object-pool.h"

Include dependency graph for promise.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	uel_promise_segment_t
	Defines a single synchronous operation to be invoked when the promise is either resolved or rejected. More...

struct	uel_promise_t
	A promise is association of an asynchronous operation to the possible execution paths that follow its resolution. It is also a holder for the value it was settled with. More...

struct	uel_promise_store_t
	An issuer of promises. Contains references to pools for promises and segments. More...

Typedefs
typedef enum uel_promise_state	uel_promise_state_t
	Alias to the `uel_promise_state` enum.

Enumerations
enum	uel_promise_state { UEL_PROMISE_PENDING, UEL_PROMISE_RESOLVED, UEL_PROMISE_REJECTED }
	Defines the possible states for a prommise. More...

Functions
uel_promise_store_t	uel_promise_store_create (uel_objpool_t promise_pool, uel_objpool_t segment_pool)
	Creates a new promise store from the promise and segment pools. More...

uel_promise_t *	uel_promise_create (uel_promise_store_t *store, uel_closure_t closure)
	Acquires a new promise from the supplied store and binds it to the asynchronous operation started by the supplied closure. The closure is invoked immediately. More...

void	uel_promise_destroy (uel_promise_t *promise)
	Destroys a promise and all of its segments. Settling this promise afterwards yields undefined behaviour. More...

void	uel_promise_then (uel_promise_t *promise, uel_closure_t resolve)
	Adds a new synchronous segment to the promise. It will be invoked upon promise resolution. In case of rejection, this segment will be ignored. More...

void	uel_promise_catch (uel_promise_t *promise, uel_closure_t reject)
	Adds a new synchronous segment to the promise. It will be invoked upon promise rejection. In case of resolution, this segment will be ignored. More...

void	uel_promise_always (uel_promise_t *promise, uel_closure_t always)
	Adds a new synchronous segment to the promise. The same closure will be invoked on promise settling regardless of the settled state. More...

void	uel_promise_after (uel_promise_t *promise, uel_closure_t resolve, uel_closure_t reject)
	Adds a new synchronous segment to the promise. Either of its closures will be invoked, depending on the settled state of the promise. More...

void	uel_promise_resolve (uel_promise_t promise, void value)
	Settles a promise as resolved and, synchronously, invokes the `resolve` closures of each segment in the order they were registered. More...

void	uel_promise_reject (uel_promise_t promise, void value)
	Settles a promise as rejected and, synchronously, invokes the `reject` closures of each segment in the order they were registered. More...

void	uel_promise_resettle (uel_promise_t promise, uel_promise_state_t state, void value)
	Resettles a promise as the supplied state. Unlike `uel_promise_resolve()` and `uel_promise_reject()`, does not invoke the synchronous segments. More...

uel_closure_t	uel_promise_resolver (uel_promise_t *promise)
	Creates a closure bound to a promise. When the closure is invoked with some parameter, the promise is resolved with this parameter as value. More...

uel_closure_t	uel_promise_rejecter (uel_promise_t *promise)
	Creates a closure bound to a promise. When the closure is invoked with some parameter, the promise is rejected with this parameter as error. More...

uel_closure_t	uel_promise_destroyer (uel_promise_t *promise)
	Creates a closure bound to a promise. When the closure is invoked, the promise is destroyed. Any parameters passed to the closure are ignored. More...

Detailed Description

Contains definitions for promise stores, promises and functions to manipulate them.

Promises are structures that associate asynchronous operations to synchronous processing of the values produces by them, allowing async data pipelines to be built.

Enumeration Type Documentation

◆ uel_promise_state

enum uel_promise_state

Defines the possible states for a prommise.

Enumerator
UEL_PROMISE_PENDING	A promise that has not been resolved nor rejected.
UEL_PROMISE_RESOLVED	A promise that has been resolved with some value.
UEL_PROMISE_REJECTED	A promise that has been rejected with some error.

Function Documentation

◆ uel_promise_after()

void uel_promise_after	(	uel_promise_t *	promise,
		uel_closure_t	resolve,
		uel_closure_t	reject
	)

Adds a new synchronous segment to the promise. Either of its closures will be invoked, depending on the settled state of the promise.

Parameters

promise	The promise to attach the segment to
resolve	The closure to be invoked when the promise is resolved
reject	The closure to be invoked when the promise is rejected

◆ uel_promise_always()

void uel_promise_always	(	uel_promise_t *	promise,
		uel_closure_t	always
	)

Adds a new synchronous segment to the promise. The same closure will be invoked on promise settling regardless of the settled state.

Parameters

promise	The promise to attach the segment to
always	The closure to be invoked when the promise is settled

◆ uel_promise_catch()

void uel_promise_catch	(	uel_promise_t *	promise,
		uel_closure_t	reject
	)

Adds a new synchronous segment to the promise. It will be invoked upon promise rejection. In case of resolution, this segment will be ignored.

Parameters

promise	The promise to attach the segment to
reject	The closure to be invoked when the promise is rejected

◆ uel_promise_create()

uel_promise_t* uel_promise_create	(	uel_promise_store_t *	store,
		uel_closure_t	closure
	)

Acquires a new promise from the supplied store and binds it to the asynchronous operation started by the supplied closure. The closure is invoked immediately.

Parameters

store	The store from where to acquire promises and segments
closure	The closure that initiates the asynchronous operation

Returns: A pointer to the promise

◆ uel_promise_destroy()

void uel_promise_destroy ( uel_promise_t * promise )

Destroys a promise and all of its segments. Settling this promise afterwards yields undefined behaviour.

Parameters

promise The promise to be destroyed

◆ uel_promise_destroyer()

uel_closure_t uel_promise_destroyer ( uel_promise_t * promise )

Creates a closure bound to a promise. When the closure is invoked, the promise is destroyed. Any parameters passed to the closure are ignored.

Parameters

promise The promise to be destroyed

Returns: A closure that destroyes the promise when invoked

◆ uel_promise_reject()

void uel_promise_reject	(	uel_promise_t *	promise,
		void *	value
	)

Settles a promise as rejected and, synchronously, invokes the reject closures of each segment in the order they were registered.

If a segment returns a non-NULL pointer, it is cast to a promise pointer and the original promise awaits until the returned promise is settled.

Parameters

promise	The promise to be rejected
value	The value to reject the promise with

◆ uel_promise_rejecter()

uel_closure_t uel_promise_rejecter ( uel_promise_t * promise )

Creates a closure bound to a promise. When the closure is invoked with some parameter, the promise is rejected with this parameter as error.

Parameters

promise The promise to be rejected

Returns: A closure that resolves the promise when invoked

◆ uel_promise_resettle()

void uel_promise_resettle	(	uel_promise_t *	promise,
		uel_promise_state_t	state,
		void *	value
	)

Resettles a promise as the supplied state. Unlike uel_promise_resolve() and uel_promise_reject(), does not invoke the synchronous segments.

This function should be used to switch execution paths during synchronous processing of segments as to signal that an error was raised or rescued by a particular segment. If the promise is settled as pending, the synchronous processing phase is interrupted.

Parameters

promise	The promise to be resettled
state	The new promise state
value	The new promise value

◆ uel_promise_resolve()

void uel_promise_resolve	(	uel_promise_t *	promise,
		void *	value
	)

Settles a promise as resolved and, synchronously, invokes the resolve closures of each segment in the order they were registered.

If a segment returns a non-NULL pointer, it is cast to a promise pointer and the original promise awaits until the returned promise is settled.

Parameters

promise	The promise to be resolved
value	The value to resolve the promise with

◆ uel_promise_resolver()

uel_closure_t uel_promise_resolver ( uel_promise_t * promise )

Creates a closure bound to a promise. When the closure is invoked with some parameter, the promise is resolved with this parameter as value.

Parameters

promise The promise to be resolved

Returns: A closure that resolves the promise when invoked

◆ uel_promise_store_create()

uel_promise_store_t uel_promise_store_create	(	uel_objpool_t *	promise_pool,
		uel_objpool_t *	segment_pool
	)

Creates a new promise store from the promise and segment pools.

Parameters

promise_pool	The `uel_objpool_t` that holds promises
segment_pool	The `uel_objpool_t` that holds segments

Returns: A new promise store bound to the object pools provided

◆ uel_promise_then()

void uel_promise_then	(	uel_promise_t *	promise,
		uel_closure_t	resolve
	)

Adds a new synchronous segment to the promise. It will be invoked upon promise resolution. In case of rejection, this segment will be ignored.

Parameters

promise	The promise to attach the segment to
resolve	The closure to be invoked when the promise is resolved

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ uel_promise_state

Function Documentation

◆ uel_promise_after()

◆ uel_promise_always()

◆ uel_promise_catch()

◆ uel_promise_create()

◆ uel_promise_destroy()

◆ uel_promise_destroyer()

◆ uel_promise_reject()

◆ uel_promise_rejecter()

◆ uel_promise_resettle()

◆ uel_promise_resolve()

◆ uel_promise_resolver()

◆ uel_promise_store_create()

◆ uel_promise_then()