cuflow/workers.h: Auxiliary Worker Threads
[SMP Work Scheduling]


int cuflow_workers_count (void)
void cuflow_workers_spawn (int target_count)
void cuflow_workers_spawn_at_least (int target_count)
void cuflow_workers_spawn_at_most (int target_count)
void cuflow_workers_call (cu_clop0(f, void))
void cuflow_workers_call_at (cu_clop(f, void, struct timespec *t_now), struct timespec *t_call)
void cuflow_workers_register_scheduler (cu_clop(sched, void, cu_bool_t))
void cuflow_yield (void)
void cuflow_workers_broadcast (void)
void cuflow_workers_incr_pending (void)
void cuflow_workers_decr_pending (void)

Detailed Description

This header provides an API to launch one or more worker threads and run functions within them, either as soon as one is idle or at a given time. The main purpose of this is to unify such work in a common framework, so that the same thread(s) can be used, rather than adding new threads for each task. The functions defined here is aimed to be the bare minimum to achieve this. For instance, if you need to know when a callback is finised, you may need to supply it's closure struct with an additional mutex and possibly a condition variable to communicate with consumer(s) of the computation.

This is implemenated purely with POSIX threads, mutices and condition variables, and in particular avoid timers or signals which may cause trouble in a multi-threaded environment.

Function Documentation

void cuflow_workers_broadcast ( void   ) 

Wake up any sleeping workers so that they can pick up any new work. You usually don't need to call this, since it's automically called by functions which add new work or unlocks existing work.

void cuflow_workers_call ( cu_clop0(f, void)   ) 

Call f in one of the worker threads, as soon as one is ready.

void cuflow_workers_call_at ( cu_clop(f, void, struct timespec *t_now)  ,
struct timespec *  t_call 

Call f at absolute CLOCK_REALTIME t_call.

int cuflow_workers_count ( void   ) 

The current number of worker threads.

void cuflow_workers_decr_pending ( void   ) 

Indicate that a unit of work signalled with cuflow_workers_incr_pending has been picked up. This is typically called from a custom scheduler.

void cuflow_workers_incr_pending ( void   ) 

Indicate that your scheduler have pending work. Pair it with a call to cuflow_workers_decr_pending when the work is done. All schedulers will run round-robin as long as this function has been called more times than cuflow_workers_decr_pending.

void cuflow_workers_register_scheduler ( cu_clop(sched, void, cu_bool_t  ) 

Arranged for sched to be called round-robin along with other registered work. This can happen either when a task is waiting for work to be completed or directly from a worker thread. When called from a worker thread, true is passed for the first argument. Otherwise, false is passed to indicate that sched is called from an arbitrary subroutine, in which case sched should only do a small amount of work and exit.

void cuflow_workers_spawn ( int  target_count  ) 

Spawn or drop worker threads until there are exactly target_count left. This is not safe to call within worker threads.

void cuflow_workers_spawn_at_least ( int  target_count  ) 

Spawns worker threads as needed so that there are at least target_count of them.

void cuflow_workers_spawn_at_most ( int  target_count  ) 

Drops worker threads as needed so that there are at most target_count left.

void cuflow_yield ( void   ) 

A call to this function performs some work which have been registered by one of the other functions from this header. This is typcially invoked when waiting for resources or results from other scheduled work.

Generated 2009-11-23 for culibs-0.25 using Doxygen. Maintained by Petter Urkedal.