---
name: "iv_work"
section: "3"
platform: "linux"
package: "libivykis-dev"
version: "0.43.2-1+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/iv_work"
---

# iv\_work(3)

ivykis worker thread management

## NAME

IV\_WORK\_POOL\_INIT, iv\_work\_pool\_create, iv\_work\_pool\_put, IV\_WORK\_ITEM\_INIT, iv\_work\_pool\_submit\_work, iv\_work\_pool\_submit\_continuation - ivykis worker thread management

## SYNOPSIS

**#include \<iv\_work.h\>**

```
struct iv_work_pool {
        int             max_threads;
        void            *cookie;
        void            (*thread_start)(void *cookie);
        void            (*thread_stop)(void *cookie);
};
struct iv_work_item {
        void            *cookie;
        void            (*work)(void *cookie);
        void            (*completion)(void *cookie);
};
```

**void IV\_WORK\_POOL\_INIT(struct iv\_work\_pool \****this***);**\
 **int iv\_work\_pool\_create(struct iv\_work\_pool \****this***);**\
 **int iv\_work\_pool\_put(struct iv\_work\_pool \****this***);**\
 **void IV\_WORK\_ITEM\_INIT(struct iv\_work\_item \****work***);**\
 **int iv\_work\_pool\_submit\_work(struct iv\_work\_pool \****this***, struct iv\_work\_item \****work***);**\
 **int iv\_work\_pool\_submit\_continuation(struct iv\_work\_pool \****this***, struct iv\_work\_item \****work***);**\

## DESCRIPTION

Calling **iv\_work\_pool\_create** on a **struct iv\_work\_pool** object previously initialised by **IV\_WORK\_POOL\_INIT** creates a pool of worker threads that can be used to offload CPU intensive tasks to, so as to prevent negatively influencing event handling latency in the calling thread, and to enable the use of multiple host CPUs for CPU intensive tasks.

**iv\_work** dynamically adjusts the number of threads in the pool to the amount of work there is to do.  The **-\>max\_threads** member of **struct iv\_work\_pool** specifies the maximum number of threads that will be created in this pool.

Calling **iv\_work\_pool\_submit\_work** on a **struct iv\_work\_item** object previously initialised by **IV\_WORK\_ITEM\_INIT** submits a work item to a pool.  The **-\>work** member of **struct iv\_work\_item** specifies the function that will be called in one of the worker threads in the pool specified by **-\>this,** with **-\>cookie** as its sole argument.  When the work function has completed, **iv\_work** will call the **-\>completion** callback to indicate this, also with **-\>cookie** as its sole argument, in the thread that **iv\_work\_pool\_create** was called in for this pool object.

Calling **iv\_work\_pool\_submit\_continuation** from a worker thread allows submitting a work item similarly to **iv\_work\_pool\_submit\_work.** But while **iv\_work\_pool\_submit\_work** can only be called from the thread owning **iv\_work,** **iv\_work\_pool\_submit\_continuation** can be called from any of the worker threads. The **-\>completion** callback of these jobs will be executed from the thread owning **iv\_work.**

As a special case, calling **iv\_work\_pool\_submit\_work** with a **NULL** work pool pointer will cause the work item to be processed in the local thread, from an [**iv\_task**(3)](/iv_task/3.md) callback.

If the **-\>thread\_start** function pointer specified in **struct iv\_work\_pool** is not NULL, it will be called upon creation of a new worker thread, in the context of the created worker thread, with **-\>cookie** as its sole argument.  Calls to **-\>thread\_start** are not explicitly serialised, which should be kept in mind when manipulating state shared between threads from within that callback function.

Similarly, if **iv\_work** decides to terminate a worker thread, for example due to inactivity, **-\>thread\_stop** will be called in the context of the terminating thread, with **-\>cookie** as its sole argument.  Calls to **-\>thread\_stop** are also not explicitly serialised.

**iv\_work\_pool\_submit\_work** can only be called from the thread that **iv\_work\_pool\_create** for this pool object was called in. **iv\_work\_pool\_submit\_continuation** can called from any of the worker threads.

There is no way to cancel submitted work items.

There is no guaranteed order, FIFO or otherwise, between different work items submitted to the same worker thread pool.

When the user has no more work items to submit to the pool, its reference to the pool can be dropped by calling **iv\_work\_pool\_put.**

If there are still pending or running work items assigned to this pool when **iv\_work\_pool\_put** is called, those work items will not be canceled, but will be allowed to run to completion, and their **-\>completion** callbacks will be called as usual.  A similar thing holds for the **-\>thread\_start** and **-\>thread\_stop** callbacks -- they can also still be called after **iv\_work\_pool\_put** returns.  Even so, the memory corresponding to the **struct iv\_work\_pool** can immediately be freed or reused by the user upon return of the **iv\_work\_pool\_put** call.

Internally, **iv\_work** uses [**iv\_thread**(3)](/iv_thread/3.md) for its thread management.

## SEE ALSO

[**ivykis**(3)](/ivykis/3.md), [**iv\_thread**(3)](/iv_thread/3.md)