Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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
       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 al-
       located 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 ini-
       tialization and cleanup.

SEE ALSO
       iv_init(3)

ivykis				  2012-03-30			     iv_tls(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=iv_tls_user_register&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help