Small library providing thread pooling capabilities
C Shell
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
src
.gitignore
COPYING.LGPL
Makefile.am
README
build.mk
buildconf.sh
configure.in

README

libspindle - small library providing thread pooling capabilities.

libspindle API
--------------

Data types
----------
spindle_t - main data struct of the thread pool, returned by spindle_create() and destroyed by spindle_destroy()
spindle_barrier_t - thread barrier struct, returned by spindle_barrier_init() and destroyed by spindle_barrier_destroy()
spindle_job_func_t - general purpose job function 
spindle_apply_func_t - thread apply function, first argument is a pointer to pthread_t

Functions
---------

/**
 * Creates a fixed-sized thread pool. 
 * If the function succeeds, it returns a non-NULL pointer to the pool struct, else it returns NULL.
 */
spindle_t *spindle_create(int num_threads_in_pool);

/**
 * Sends a thread off to do some work.  If all threads in the pool are busy, dispatch will
 * block until a thread becomes free and is dispatched.
 * 
 * Once a thread is dispatched, this function returns immediately.
 *
 * Also enables the user to define cleanup handlers in 
 * cases of immediate cancel.  The cleanup handler function (cleaner_func) is 
 * executed automatically with cleaner_arg as the argument after the 
 * dispatch_to_here function is done; in the case that the thread is destroyed,
 * cleaner_func is also called before the thread exits.
 */
void spindle_dispatch_with_cleanup(spindle_t *from_me, spindle_barrier_t *barrier, spindle_job_func_t dispatch_to_here, void * arg, spindle_job_func_t cleaner_func, void* cleaner_arg);

/**
 * The dispatched thread calls the function "dispatch_to_here" with argument "arg".
 */
#define spindle_dispatch(from, barrier, to, arg) spindle_dispatch_with_cleanup((from), (barrier), (to), (arg), NULL, NULL)

/**
 * Apply a function to all threads in the pool. 
 * */
void spindle_apply(spindle_t *p, spindle_apply_func_t func, void *arg);

/**
 * Kills the threadpool, causing all threads in it to commit suicide, 
 * and then frees all the memory associated with the threadpool.
 */
void spindle_destroy(spindle_t *destroyme);

/**
 * Cancels all threads in the threadpool immediately.
 * It is potentially dangerous to use with libraries that are not specifically 
 * asynchronous cancel thread safe. Also, without cleanup handlers, any dynamic 
 * memory or system resource in use could potentially be left without a reference
 * to it. 
 */
void spindle_destroy_immediately(spindle_t *destroymenow);

/**
 * Creates and initializes barrier struct.
 */
spindle_barrier_t *spindle_barrier_create(void);

/**
 * Starts the barrier, after that point all calls to spindle_dispatch*() have to use this barrier. 
 */
int spindle_barrier_start(spindle_barrier_t *b);

/**
 * Waits for the threads to finish their jobs and continues after all of the workers have finished.
 */
void spindle_barrier_wait(spindle_barrier_t *b);

/**
 * Destroys and frees the barrier internal struct.
 */
void spindle_barrier_destroy(spindle_barrier_t *b);

/**
 * A shortcut for _wait() + _destroy()
 */
void spindle_barrier_end(spindle_barrier_t *b);