home | help 
iv_tls(3)		   ivykis programmer's manual		       iv_tls(3)

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  mod-
     ules.

     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  construc-
     tor 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 allo-
     cated 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 in-
     voked 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)

ivykis				   2012-03-30			       iv_tls(3)
home | help