iv_tls(3)

1iv_tls(3)                 ivykis programmer's manual                 iv_tls(3)
2
3
4

NAME

6       iv_tls_user_register,  iv_tls_user_ptr  - thread-local storage handling
7       for ivykis modules
8

SYNOPSIS

10       #include <iv_tls.h>
11
12       struct iv_tls_user {
13               size_t          sizeof_state;
14               void            (*init_thread)(void *st);
15               void            (*deinit_thread)(void *st);
16       };
17
18       void iv_tls_user_register(struct iv_tls_user *tu);
19       void *iv_tls_user_ptr(const struct iv_tls_user *tu);
20

DESCRIPTION

22       The iv_tls interface provides thread-local storage handling  to  ivykis
23       modules.
24
25       An  ivykis  module  can arrange for an amount of memory to be allocated
26       for its use in each  ivykis  thread  by  calling  iv_tls_user_register.
27       This  must  be  done before any calls to iv_init have been made in this
28       process, and is typically done from a  module  initialization  function
29       marked as a constructor function.
30
31       The ->sizeof_state member of the passed-in structure indicates how many
32       bytes of memory the module wants allocated for its use in every  ivykis
33       thread.
34
35       When  a  thread  calls  iv_init, ->sizeof_state bytes of memory will be
36       allocated for use by this module in that  thread,  and  initialised  to
37       zero.   A  pointer  to  this  memory  area  can  be obtained by calling
38       iv_tls_user_ptr (which returns NULL in non-ivykis threads).
39
40       If the specified ->init_thread function pointer is not NULL, it will be
41       invoked  at  the  end  of  iv_init,  with its argument pointing to this
42       thread's memory area allocation for this module.
43
44       If ->deinit_thread is not NULL, it will be  invoked  at  the  start  of
45       iv_deinit, or if the thread fails to call iv_deinit before terminating,
46       at thread termination time.  The argument passed  into  ->deinit_thread
47       is the same as for ->init_thread.
48
49       It is permitted to call any ivykis API functions from the ->init_thread
50       and ->deinit_thread callbacks.
51
52       There is no  explicit  serialization  on  calls  to  ->init_thread  and
53       ->deinit_thread.
54
55       Care  must be taken when calling iv_tls_user_ptr from a signal handler,
56       as there is a time window where it will return a non-NULL value  before
57       ->init_thread or after ->deinit_thread have been called.
58
59       Use  of iv_tls for managing thread-local state is preferred over direct
60       use of the __thread keyword, as not all platforms that ivykis  runs  on
61       provide the __thread keyword.
62
63       Use  of iv_tls for managing thread-local state is preferred over direct
64       use of the pthread_key_create and pthread_setspecific APIs,  as  iv_tls
65       provides  a thread init hook as well as a destructor hook, and properly
66       sequences ->init_thread and ->deinit_thread calls with core ivykis ini‐
67       tialization and cleanup.
68

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO