iv\_tls(3) ivykis programmer's manual iv\_tls(3)

# [NAME](#NAME)

iv\_tls\_user\_register, iv\_tls\_user\_ptr - thread-local storage handling for ivykis modules

# [SYNOPSIS](#SYNOPSIS)

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

```
struct iv_tls_user {


        size_t          sizeof_state;


        void            (*init_thread)(void *st);


        void            (*deinit_thread)(void *st);
};
```

**void iv\_tls\_user\_register(struct iv\_tls\_user \*tu);**  
**void \*iv\_tls\_user\_ptr(const struct iv\_tls\_user \*tu);**

# [DESCRIPTION](#DESCRIPTION)

The **iv\_tls** interface provides thread-local storage handling to **ivykis** modules.

An ivykis module can arrange for an amount of memory to be allocated for its use in each ivykis thread by calling **iv\_tls\_user\_register.** This must be done before any calls to **iv\_init** have been made in this process, and is typically done from a module initialization function marked as a constructor function.

The **->sizeof\_state** member of the passed-in structure indicates how many bytes of memory the module wants allocated for its use in every ivykis thread.

When a thread calls **iv\_init,** **->sizeof\_state** bytes of memory will be allocated for use by this module in that thread, and initialised to zero. A pointer to this memory area can be obtained by calling **iv\_tls\_user\_ptr** (which returns NULL in non-ivykis threads).

If the specified **->init\_thread** function pointer is not NULL, it will be invoked at the end of **iv\_init,** with its argument pointing to this thread's memory area allocation for this module.

If **->deinit\_thread** is not NULL, it will be invoked at the start of **iv\_deinit,** or if the thread fails to call **iv\_deinit** before terminating, at thread termination time. The argument passed into **->deinit\_thread** is the same as for **->init\_thread.**

It is permitted to call any ivykis API functions from the **->init\_thread** and **->deinit\_thread** callbacks.

There is no explicit serialization on calls to **->init\_thread** and **->deinit\_thread.**

Care must be taken when calling **iv\_tls\_user\_ptr** from a signal handler, as there is a time window where it will return a non-NULL value before **->init\_thread** or after **->deinit\_thread** have been called.

Use of **iv\_tls** for managing thread-local state is preferred over direct use of the **\_\_thread** keyword, as not all platforms that ivykis runs on provide the **\_\_thread** keyword.

Use of **iv\_tls** for managing thread-local state is preferred over direct use of the **pthread\_key\_create** and **pthread\_setspecific** APIs, as **iv\_tls** provides a thread init hook as well as a destructor hook, and properly sequences **->init\_thread** and **->deinit\_thread** calls with core ivykis initialization and cleanup.

# [SEE ALSO](#SEE_ALSO)

[**iv\_init**(3)](/man/os/ivykis/iv_init.3)

2012-03-30 ivykis

---

Document: iv_tls_user_register(3) from ivykis 0.43.2-r8 (Chainguard OS)
Source: https://github.com/buytenh/ivykis