---
name: "iv_tls"
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_tls"
---

# iv\_tls(3)

thread-local storage handling for ivykis modules

## NAME

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

## 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

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

[**iv\_init**(3)](/iv_init/3.md)