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)