libwp 0.1 review

libwp provides a simplified facility for a common use of threads, processing tasks using a pool of threads. libwp is implemented w

License: CDDL (Common Development and Distribution License) File size: 314K Developer: Gary Pennington

0

libwp provides a simplified facility for a common use of threads, processing tasks using a pool of threads.

libwp is implemented with POSIX threads (pthreads) for the Solaris and Linux platforms. The primary development platform is Solaris.

Usage:

Creating a Pool

Before you can do any processing with libwp you must create a pool using wp_new(). This will create and configure your pool and populate it with the required number of worker threads. If you don't specify a number of threads (i.e. size is 0), then libwp will automatically calculate a number of threads which are appropriate for the number of available processors. The function pointers you provide are the default functions used to execute and report on submitted tasks.

Using a Pool

Once you've created your pool, you can go ahead and run tasks in the pool. You queue a task for execution with wp_run() or wp_run_task(). If a worker thread is available then the task will be immediately allocated to the thread and processed. If there are no available worker threads then the task will be queued for processing when a thread becomes available.

wp_run() will use the default process and report arguments supplied when the pool was created (see wp_new()). wp_run_task() uses the supplied process and report arguments.

Destroying a Pool

Once you are finished with a pool, then you should destroy it with wp_free(). Destroying the pool will reclaim all resources associated with the pool. This is a blocking call and the invoking thread will wait until all currently active threads terminate before returning. The wait flag controls the behaviour of the function. If WP_WAIT is specified, then the pool will not be destroyed until there are no active threads. Whilst it is waiting for this to occur additional task requests may be queued. If WP_IMMEDIATE is specified, then the pool will not accept more task requests and will be destroyed as soon as all active task are finished.

Utility Functions

The two message logging functions (wp_log() and wp_die()) are synchronized so that all messages are displayed atomically.

wp_close() can be used to close a pool. This has the same effect as calling wp_free() but does not reclaim the pool resources.
wp_open() can be used to re-open a previously closed (wp_close()) pool.
wp_resize() can be used to resize a currently open and active pool.
wp_wait() can be used to cause a thread to wait for a worker pool to quiesce, i.e. no outstanding jobs in the pool. Be careful using this function as external co-ordination is required to prevent race conditions from developing.
wp_active() can be used to determine how many worker threads are currently busy and wp_state() is used to determine if the worker pool is still accepting new tasks. Once a pool is closed, state of WP_INACTIVE, it will no longer accept further task requests.
wp_enable_stats() can be used to cause the pool to start collecting performance statistics. These statistics can be retrieved and examined using wp_get_stats(). Statistics collection is disabled using wp_disable_stats().