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(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)