KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
tls.h
Go to the documentation of this file.
1 /* KallistiOS ##version##
2 
3  include/kos/tls.h
4  Copyright (C) 2009, 2010 Lawrence Sebald
5 
6 */
7 
8 /** \file kos/tls.h
9  \brief Thread-local storage support.
10 
11  This file contains the definitions used to support key/value pairs of
12  thread-local storage in KOS.
13 
14  \author Lawrence Sebald
15 */
16 
17 #ifndef __KOS_TLS_H
18 #define __KOS_TLS_H
19 
20 #include <sys/cdefs.h>
21 
22 __BEGIN_DECLS
23 
24 #include <sys/queue.h>
25 
26 /** \brief Thread-local storage key type. */
27 typedef int kthread_key_t;
28 
29 /** \brief Thread-local storage key-value pair.
30 
31  This is the structure that is actually used to store the specific value for
32  a thread for a single TLS key.
33 
34  You will not end up using these directly at all in programs, as they are
35  only used internally.
36 */
37 typedef struct kthread_tls_kv {
38  /** \brief List handle -- NOT a function. */
39  LIST_ENTRY(kthread_tls_kv) kv_list;
40 
41  /** \brief The key associated with this data. */
43 
44  /** \brief The value of the data. */
45  void *data;
46 
47  /** \brief Optional destructor for the value (set per key). */
48  void (*destructor)(void *);
50 
51 /** \cond */
52 /* TLS Key-Value pair list type. */
53 LIST_HEAD(kthread_tls_kv_list, kthread_tls_kv);
54 /** \endcond */
55 
56 /** \cond */
57 /* Retrieve the next key value (i.e, what key the next kthread_key_create will
58  use). This function is not meant for external use (although it won't really
59  hurt anything for you to call it). */
60 kthread_key_t kthread_key_next();
61 /** \endcond */
62 
63 /** \brief Create a new thread-local storage key.
64 
65  This function creates a new thread-local storage key that shall be visible
66  to all threads. Each thread is then responsible for associating any data
67  with the key that it deems fit (by default a thread will have no data
68  associated with a newly created key).
69 
70  \param key The key to use.
71  \param destructor A destructor for use with this key. If it is non-NULL,
72  and a value associated with the key is non-NULL at
73  thread exit, then the destructor will be called with the
74  value as its argument.
75  \retval -1 On failure, and sets errno to one of the following: EPERM if
76  called inside an interrupt and another call is in progress,
77  ENOMEM if out of memory.
78  \retval 0 On success.
79 */
80 int kthread_key_create(kthread_key_t *key, void (*destructor)(void *));
81 
82 /** \brief Retrieve a value associated with a TLS key.
83 
84  This function retrieves the thread-specific data associated with the given
85  key.
86 
87  \param key The key to look up data for.
88  \return The data associated with the key, or NULL if the key is not valid or
89  no data has been set in the current thread.
90 */
92 
93 /** \brief Set thread specific data for a key.
94 
95  This function sets the thread-specific data associated with the given key.
96 
97  \param key The key to set data for.
98  \param value The thread-specific value to use.
99  \retval -1 On failure, and sets errno to one of the following: EINVAL
100  if the key is not valid, ENOMEM if out of memory, or EPERM
101  if called inside an interrupt and another call is in
102  progress.
103  \retval 0 On success.
104 */
105 int kthread_setspecific(kthread_key_t key, const void *value);
106 
107 /** \brief Delete a TLS key.
108 
109  This function deletes a TLS key, removing all threads' values for the given
110  key. This function <em>does not</em> cause any destructors to be called.
111 
112  \param key The key to delete.
113  \retval -1 On failure, and sets errno to one of the following: EINVAL
114  if the key is invalid, EPERM if unsafe to call free.
115  \retval 0 On success.
116 */
118 
119 /** \cond */
120 /* Delete the destructor for a given key. This function is for internal use
121  only! */
122 void kthread_key_delete_destructor(kthread_key_t key);
123 
124 /* Initialization and shutdown. Once again, internal use only. */
125 int kthread_tls_init();
126 void kthread_tls_shutdown();
127 /** \endcond */
128 
129 __END_DECLS
130 
131 #endif /* __KOS_TLS_H */
struct kthread_tls_kv kthread_tls_kv_t
Thread-local storage key-value pair.
int kthread_key_create(kthread_key_t *key, void(*destructor)(void *))
Create a new thread-local storage key.
LIST_ENTRY(kthread_tls_kv) kv_list
List handle – NOT a function.
int kthread_key_delete(kthread_key_t key)
Delete a TLS key.
typedef LIST_HEAD(nmmgr_list, nmmgr_handler) nmmgr_list_t
Name handler list type.
Thread-local storage key-value pair.
Definition: tls.h:37
kthread_key_t key
The key associated with this data.
Definition: tls.h:42
void * kthread_getspecific(kthread_key_t key)
Retrieve a value associated with a TLS key.
int kthread_setspecific(kthread_key_t key, const void *value)
Set thread specific data for a key.
void * data
The value of the data.
Definition: tls.h:45
void(* destructor)(void *)
Optional destructor for the value (set per key).
Definition: tls.h:48
int kthread_key_t
Thread-local storage key type.
Definition: tls.h:27