git.mutantstargoat.com Git - assman/blob - src/tpool.h

   1 /* worker thread pool based on POSIX threads
   2  * author: John Tsiombikas <nuclear@member.fsf.org>
   3  * This code is public domain.
   4  */
   5 #ifndef ASSMAN_THREADPOOL_H_
   6 #define ASSMAN_THREADPOOL_H_
   7
   8 struct thread_pool;
   9
  10 /* type of the function accepted as work or completion callback */
  11 typedef void (*tpool_callback)(void*);
  12
  13 #ifdef __cplusplus
  14 extern "C" {
  15 #endif
  16
  17 /* if num_threads == 0, auto-detect how many threads to spawn */
  18 struct thread_pool *ass_tpool_create(int num_threads);
  19 void ass_tpool_destroy(struct thread_pool *tpool);
  20
  21 /* optional reference counting interface for thread pool sharing */
  22 int ass_tpool_addref(struct thread_pool *tpool);
  23 int ass_tpool_release(struct thread_pool *tpool);       /* will ass_tpool_destroy on nref 0 */
  24
  25 /* if begin_batch is called before an enqueue, the worker threads will not be
  26  * signalled to start working until end_batch is called.
  27  */
  28 void ass_tpool_begin_batch(struct thread_pool *tpool);
  29 void ass_tpool_end_batch(struct thread_pool *tpool);
  30
  31 /* if enqueue is called without calling begin_batch first, it will immediately
  32  * wake up the worker threads to start working on the enqueued item
  33  */
  34 int ass_tpool_enqueue(struct thread_pool *tpool, void *data,
  35                 tpool_callback work_func, tpool_callback done_func);
  36 /* clear the work queue. does not cancel any currently running jobs */
  37 void ass_tpool_clear(struct thread_pool *tpool);
  38
  39 /* returns the number of queued work items */
  40 int ass_tpool_queued_jobs(struct thread_pool *tpool);
  41 /* returns the number of active (working) threads */
  42 int ass_tpool_active_jobs(struct thread_pool *tpool);
  43 /* returns the number of pending jobs, both in queue and active */
  44 int ass_tpool_pending_jobs(struct thread_pool *tpool);
  45
  46 /* wait for all pending jobs to be completed */
  47 void ass_tpool_wait(struct thread_pool *tpool);
  48 /* wait until the pending jobs are down to the target specified
  49  * for example, to wait until a single job has been completed:
  50  *   ass_tpool_wait_pending(tpool, ass_tpool_pending_jobs(tpool) - 1);
  51  * this interface is slightly awkward to avoid race conditions. */
  52 void ass_tpool_wait_pending(struct thread_pool *tpool, int pending_target);
  53 /* wait for all pending jobs to be completed for up to "timeout" milliseconds */
  54 long ass_tpool_timedwait(struct thread_pool *tpool, long timeout);
  55
  56 /* return a file descriptor which can be used to wait for pending job
  57  * completion events. A single char is written every time a job completes.
  58  * You should empty the pipe every time you receive such an event.
  59  *
  60  * This is a UNIX-specific call. On windows it does nothing.
  61  */
  62 int ass_tpool_get_wait_fd(struct thread_pool *tpool);
  63
  64 /* return an auto-resetting Event HANDLE which can be used to wait for
  65  * pending job completion events.
  66  *
  67  * This is a Win32-specific call. On UNIX it does nothing.
  68  */
  69 void *ass_tpool_get_wait_handle(struct thread_pool *tpool);
  70
  71 /* When called by a work/done callback, it returns the thread number executing
  72  * it. From the main thread it returns -1.
  73  */
  74 int ass_tpool_thread_id(struct thread_pool *tpool);
  75
  76 /* returns the number of processors on the system.
  77  * individual cores in multi-core processors are counted as processors.
  78  */
  79 int ass_tpool_num_processors(void);
  80
  81 #ifdef __cplusplus
  82 }
  83 #endif
  84
  85 #endif  /* ASSMAN_THREADPOOL_H_ */