1iv_work(3)                ivykis programmer's manual                iv_work(3)


6       IV_WORK_POOL_INIT,        iv_work_pool_create,        iv_work_pool_put,
7       IV_WORK_ITEM_INIT, iv_work_pool_submit_work - ivykis worker thread man‐
8       agement


11       #include <iv_work.h>
13       struct iv_work_pool {
14               int             max_threads;
15               void            *cookie;
16               void            (*thread_start)(void *cookie);
17               void            (*thread_stop)(void *cookie);
18       };
20       struct iv_work_item {
21               void            *cookie;
22               void            (*work)(void *cookie);
23               void            (*completion)(void *cookie);
24       };
26       void IV_WORK_POOL_INIT(struct iv_work_pool *this);
27       int iv_work_pool_create(struct iv_work_pool *this);
28       int iv_work_pool_put(struct iv_work_pool *this);
29       void IV_WORK_ITEM_INIT(struct iv_work_item *work);
30       int    iv_work_pool_submit_work(struct   iv_work_pool   *this,   struct
31       iv_work_item *work);


34       Calling iv_work_pool_create on a struct iv_work_pool object  previously
35       initialised  by IV_WORK_POOL_INIT creates a pool of worker threads that
36       can be used to offload CPU intensive tasks to, so as to  prevent  nega‐
37       tively influencing event handling latency in the calling thread, and to
38       enable the use of multiple host CPUs for CPU intensive tasks.
40       iv_work dynamically adjusts the number of threads in the  pool  to  the
41       amount  of  work  there  is  to do.  The ->max_threads member of struct
42       iv_work_pool specifies the maximum number of threads that will be  cre‐
43       ated in this pool.
45       Calling iv_work_pool_submit_work on a struct iv_work_item object previ‐
46       ously initialised by IV_WORK_ITEM_INIT submits a work item to  a  pool.
47       The  ->work  member  of struct iv_work_item specifies the function that
48       will be called in one of the worker threads in the  pool  specified  by
49       ->this, with ->cookie as its sole argument.  When the work function has
50       completed, iv_work will call  the  ->completion  callback  to  indicate
51       this,  also  with  ->cookie  as  its  sole argument, in the thread that
52       iv_work_pool_create was called in for this pool object.
54       As a special case, calling iv_work_pool_submit_work with  a  NULL  work
55       pool  pointer  will  cause  the  work item to be processed in the local
56       thread, from an iv_task(3) callback.
58       If the ->thread_start function pointer specified in struct iv_work_pool
59       is not NULL, it will be called upon creation of a new worker thread, in
60       the context of the created worker thread, with  ->cookie  as  its  sole
61       argument.  Calls to ->thread_start are not explicitly serialised, which
62       should be kept in mind when manipulating state shared  between  threads
63       from within that callback function.
65       Similarly, if iv_work decides to terminate a worker thread, for example
66       due to inactivity, ->thread_stop will be called in the context  of  the
67       terminating  thread,  with  ->cookie  as  its  sole argument.  Calls to
68       ->thread_stop are also not explicitly serialised.
70       iv_work_pool_submit_work can  only  be  called  from  the  thread  that
71       iv_work_pool_create for this pool object was called in.
73       There is no way to cancel submitted work items.
75       There is no guaranteed order, FIFO or otherwise, between different work
76       items submitted to the same worker thread pool.
78       When the user has no more work items to submit to the pool, its  refer‐
79       ence to the pool can be dropped by calling iv_work_pool_put.
81       If  there are still pending or running work items assigned to this pool
82       when iv_work_pool_put is called, those work items will not be canceled,
83       but  will be allowed to run to completion, and their ->completion call‐
84       backs will  be  called  as  usual.   A  similar  thing  holds  for  the
85       ->thread_start  and  ->thread_stop  callbacks -- they can also still be
86       called after iv_work_pool_put returns.  Even so, the memory correspond‐
87       ing  to  the  struct iv_work_pool can immediately be freed or reused by
88       the user upon return of the iv_work_pool_put call.
90       Internally, iv_work uses iv_thread(3) for its thread management.


93       ivykis(3), iv_thread(3)
97ivykis                            2010-09-14                        iv_work(3)