cuflow/promise.h: Delayed Fulfillment of Computations
[[deprecated] Old SMP Work Scheduling]

Data Structures
struct	cuflow_promise
Defines
#define	cuflow_promise_state_latent   0
#define	cuflow_promise_state_initiated   1
#define	cuflow_promise_state_fulfilled   0x8000
Typedefs
typedef int	cuflow_promise_state_t
Functions
typedef	cu_clop (cuflow_promise_initiator_t, void, cuflow_promise_t)
void	cuflow_promise_init (cuflow_promise_t promise, cu_clop(initiator, void, cuflow_promise_t))
void	cuflowP_promise_process (cuflow_promise_t promise, cuflow_promise_state_t state)
cuflow_promise_state_t	cuflow_promise_state (cuflow_promise_t promise)
void	cuflow_promise_set_state (cuflow_promise_t promise, cuflow_promise_state_t state)
void	cuflow_promise_set_fulfilled (cuflow_promise_t promise, void *ptr)
cuflow_promise_state_t	cuflow_promise_increment_state (cuflow_promise_t promise)
void	cuflow_promise_process (cuflow_promise_t promise, cuflow_promise_state_t state)
void *	cuflow_promise_fulfill (cuflow_promise_t promise)
void *	cuflow_promise_mem (cuflow_promise_t promise)

---

Detailed Description

Deprecated:

Similar functionality is provided by cuflow/sched.h using cuflow/cdisj.h for guarding the result of a computation.

A promise is a handle which contains a task to be performed at a later time, and a state of the computation. The computation may schedule further work on the global work queue, in which case other threads requesting the computation can take part in the workload.

The state is initially cuflow_promise_state_latent. When the promise is requested, the state is updated to cuflow_promise_state_initiated before the main task is called. Subsequent states may be written to the promise by the computation to represent various degrees of fulfillment. In the simplest case there is one more states, meaning that the promise is fulfilled. When working on recursive structures, a four-state promise may be needed, where first additional state means that a data-structure is allocated so that the pointer is available for linking, and the last state means that the data structure is constructed and thus fully usable.

---

Define Documentation

#define cuflow_promise_state_fulfilled   0x8000

When this state or a higher state is written to the promise by the client implementation, which may be either the initiator or a job submitted by it, the reference to the work queue will be unlinked from the promise, so that it can be freed by the collector when it becomes empty (though it will usually already be empty).

#define cuflow_promise_state_initiated   1

The promise has been requested and the main task have been started.

#define cuflow_promise_state_latent   0

The promise has not yet been requested.

---

Typedef Documentation

typedef int cuflow_promise_state_t

The state of a promise.

---

Function Documentation

void* cuflow_promise_fulfill

(

cuflow_promise_t

promise

)

Fulfill promise upto cuflow_promise_state_fulfilled, and return the value that it set with cuflow_promise_set_fulfilled. Some promises may wish to store the value elsewhere, like after the promise struct.

cuflow_promise_state_t cuflow_promise_increment_state

(

cuflow_promise_t

promise

)

Increment the state of promise and return the post value.

void cuflow_promise_init	(	cuflow_promise_t	promise,
		cu_clop(initiator, void, cuflow_promise_t)
	)

Construct promise which will be fulfilled by calling initiator and performing any work which it passes onto the work queue of promise.

void* cuflow_promise_mem

(

cuflow_promise_t

promise

)

Returns a pointer to the end of the promise struct itself, which may be used by client, if allocated, to store working state or final data.

void cuflow_promise_process	(	cuflow_promise_t	promise,
		cuflow_promise_state_t	state
	)

Fulfill promise upto state by calling the initiator if not already done, then call the work queue and possibly wait for other threads which process the promise, until the state is reached.

void cuflow_promise_set_fulfilled	(	cuflow_promise_t	promise,
		void *	ptr
	)

Set the state of promise to cuflow_promise_state_fulfilled and store ptr with its value. Data stored before this state is reached must be stored elsewhere, like after the promise struct, cf cuflow_promise_mem, or by embedding the promise struct in a larger struct. In that can you may pass ptr to point to it, or ptr = NULL.

void cuflow_promise_set_state	(	cuflow_promise_t	promise,
		cuflow_promise_state_t	state
	)

Set the state of promise to state.

Precondition:

state is greater than the current state.

cuflow_promise_state_t cuflow_promise_state

(

cuflow_promise_t

promise

)

Return the current state of the promise.