1 /* worker thread pool based on POSIX threads
2 * author: John Tsiombikas <nuclear@member.fsf.org>
3 * This code is public domain.
10 /* type of the function accepted as work or completion callback */
11 typedef void (*tpool_callback)(void*);
17 /* if num_threads == 0, auto-detect how many threads to spawn */
18 struct thread_pool *tpool_create(int num_threads);
19 void tpool_destroy(struct thread_pool *tpool);
21 /* optional reference counting interface for thread pool sharing */
22 int tpool_addref(struct thread_pool *tpool);
23 int tpool_release(struct thread_pool *tpool); /* will tpool_destroy on nref 0 */
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.
28 void tpool_begin_batch(struct thread_pool *tpool);
29 void tpool_end_batch(struct thread_pool *tpool);
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
34 int 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 tpool_clear(struct thread_pool *tpool);
39 /* returns the number of queued work items */
40 int tpool_queued_jobs(struct thread_pool *tpool);
41 /* returns the number of active (working) threads */
42 int tpool_active_jobs(struct thread_pool *tpool);
43 /* returns the number of pending jobs, both in queue and active */
44 int tpool_pending_jobs(struct thread_pool *tpool);
46 /* wait for all pending jobs to be completed */
47 void 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 * tpool_wait_pending(tpool, tpool_pending_jobs(tpool) - 1);
51 * this interface is slightly awkward to avoid race conditions. */
52 void 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 tpool_timedwait(struct thread_pool *tpool, long timeout);
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.
60 * This is a UNIX-specific call. On windows it does nothing.
62 int tpool_get_wait_fd(struct thread_pool *tpool);
64 /* return an auto-resetting Event HANDLE which can be used to wait for
65 * pending job completion events.
67 * This is a Win32-specific call. On UNIX it does nothing.
69 void *tpool_get_wait_handle(struct thread_pool *tpool);
71 /* When called by a work/done callback, it returns the thread number executing
72 * it. From the main thread it returns -1.
74 int tpool_thread_id(struct thread_pool *tpool);
77 /* returns the number of processors on the system.
78 * individual cores in multi-core processors are counted as processors.
80 int tpool_num_processors(void);
86 #endif /* THREADPOOL_H_ */