KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
pthread.h
Go to the documentation of this file.
1 /* pthread.h
2  *
3  * Written by Joel Sherrill <joel@OARcorp.com>.
4  *
5  * COPYRIGHT (c) 1989-2000.
6  * On-Line Applications Research Corporation (OAR).
7  *
8  * Permission to use, copy, modify, and distribute this software for any
9  * purpose without fee is hereby granted, provided that this entire notice
10  * is included in all copies of any software which is or includes a copy
11  * or modification of this software.
12  *
13  * THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
14  * WARRANTY. IN PARTICULAR, THE AUTHOR MAKES NO REPRESENTATION
15  * OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS
16  * SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
17  *
18  */
19 
20 // Need a local copy of this because the default one is buggy.
21 
22 /** \file pthread.h
23  \brief POSIX-compatibile (sorta) threading support.
24 
25  This file was imported (with a few changes) from Newlib. If you really want
26  to know about the functions in here, you should probably consult the Single
27  Unix Specification and the POSIX specification. Here's a link to that:
28  http://pubs.opengroup.org/onlinepubs/007904875/basedefs/pthread.h.html
29 
30  The rest of this file will remain undocumented, as it isn't really a part of
31  KOS proper... Also, doxygen tends to mangle this whole thing anyway...
32 */
33 
34 /** \cond */
35 
36 #ifndef __PTHREAD_h
37 #define __PTHREAD_h
38 
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42 
43 #include <unistd.h>
44 #include <sys/_pthread.h>
45 
46 #if defined(_POSIX_THREADS)
47 
48 #include <sys/types.h>
49 #include <time.h>
50 #include <sys/sched.h>
51 
52  /* Register Fork Handlers, P1003.1c/Draft 10, P1003.1c/Draft 10, p. 27
53 
54  If an OS does not support processes, then it falls under this provision
55  and may not provide pthread_atfork():
56 
57  "Either the implementation shall support the pthread_atfork() function
58  as described above or the pthread_atfork() funciton shall not be
59  provided."
60 
61  NOTE: RTEMS does not provide pthread_atfork(). */
62 
63 #if !defined(__rtems__)
64 // #warning "Add pthread_atfork() prototype"
65 #endif
66 
67  /* Mutex Initialization Attributes, P1003.1c/Draft 10, p. 81 */
68 
69  int _EXFUN(pthread_mutexattr_init, (pthread_mutexattr_t *attr));
70  int _EXFUN(pthread_mutexattr_destroy, (pthread_mutexattr_t *attr));
71  int _EXFUN(pthread_mutexattr_getpshared,
72  (const pthread_mutexattr_t *attr, int *pshared));
73  int _EXFUN(pthread_mutexattr_setpshared,
74  (pthread_mutexattr_t *attr, int pshared));
75 
76  /* Initializing and Destroying a Mutex, P1003.1c/Draft 10, p. 87 */
77 
78  int _EXFUN(pthread_mutex_init,
79  (pthread_mutex_t *mutex, const pthread_mutexattr_t *attr));
80  int _EXFUN(pthread_mutex_destroy, (pthread_mutex_t *mutex));
81 
82  /* This is used to statically initialize a pthread_mutex_t. Example:
83 
84  pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
85  */
86 
87 #define PTHREAD_MUTEX_INITIALIZER MUTEX_INITIALIZER
88 
89  /* Locking and Unlocking a Mutex, P1003.1c/Draft 10, p. 93
90  NOTE: P1003.4b/D8 adds pthread_mutex_timedlock(), p. 29 */
91 
92  int _EXFUN(pthread_mutex_lock, (pthread_mutex_t *mutex));
93  int _EXFUN(pthread_mutex_trylock, (pthread_mutex_t *mutex));
94  int _EXFUN(pthread_mutex_unlock, (pthread_mutex_t *mutex));
95 
96 #if defined(_POSIX_TIMEOUTS)
97 
98  int _EXFUN(pthread_mutex_timedlock,
99  (pthread_mutex_t *mutex, const struct timespec *timeout));
100 
101 #endif /* _POSIX_TIMEOUTS */
102 
103  /* Condition Variable Initialization Attributes, P1003.1c/Draft 10, p. 96 */
104 
105  int _EXFUN(pthread_condattr_init, (pthread_condattr_t *attr));
106  int _EXFUN(pthread_condattr_destroy, (pthread_condattr_t *attr));
107  int _EXFUN(pthread_condattr_getpshared,
108  (const pthread_condattr_t *attr, int *pshared));
109  int _EXFUN(pthread_condattr_setpshared,
110  (pthread_condattr_t *attr, int pshared));
111 
112  /* Initializing and Destroying a Condition Variable, P1003.1c/Draft 10, p. 87 */
113 
114  int _EXFUN(pthread_cond_init,
115  (pthread_cond_t *cond, const pthread_condattr_t *attr));
116  int _EXFUN(pthread_cond_destroy, (pthread_cond_t *cond));
117 
118  /* This is used to statically initialize a pthread_cond_t. Example:
119 
120  pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
121  */
122 
123 #define PTHREAD_COND_INITIALIZER COND_INITIALIZER
124 
125  /* Broadcasting and Signaling a Condition, P1003.1c/Draft 10, p. 101 */
126 
127  int _EXFUN(pthread_cond_signal, (pthread_cond_t *cond));
128  int _EXFUN(pthread_cond_broadcast, (pthread_cond_t *cond));
129 
130  /* Waiting on a Condition, P1003.1c/Draft 10, p. 105 */
131 
132  int _EXFUN(pthread_cond_wait,
133  (pthread_cond_t *cond, pthread_mutex_t *mutex));
134 
135  int _EXFUN(pthread_cond_timedwait,
136  (pthread_cond_t *cond, pthread_mutex_t *mutex,
137  const struct timespec *abstime));
138 
139 #if defined(_POSIX_THREAD_PRIORITY_SCHEDULING)
140 
141  /* Thread Creation Scheduling Attributes, P1003.1c/Draft 10, p. 120 */
142 
143  int _EXFUN(pthread_attr_setscope,
144  (pthread_attr_t *attr, int contentionscope));
145  int _EXFUN(pthread_attr_getscope,
146  (const pthread_attr_t *attr, int *contentionscope));
147  int _EXFUN(pthread_attr_setinheritsched,
148  (pthread_attr_t *attr, int inheritsched));
149  int _EXFUN(pthread_attr_getinheritsched,
150  (const pthread_attr_t *attr, int *inheritsched));
151  int _EXFUN(pthread_attr_setschedpolicy, (pthread_attr_t *attr, int policy));
152  int _EXFUN(pthread_attr_getschedpolicy,
153  (const pthread_attr_t *attr, int *policy));
154 
155 #endif /* defined(_POSIX_THREAD_PRIORITY_SCHEDULING) */
156 
157  int _EXFUN(pthread_attr_setschedparam,
158  (pthread_attr_t *attr, const struct sched_param *param));
159  int _EXFUN(pthread_attr_getschedparam,
160  (const pthread_attr_t *attr, struct sched_param *param));
161 
162 #if defined(_POSIX_THREAD_PRIORITY_SCHEDULING)
163 
164  /* Dynamic Thread Scheduling Parameters Access, P1003.1c/Draft 10, p. 124 */
165 
166  int _EXFUN(pthread_getschedparam,
167  (pthread_t thread, int *policy, struct sched_param *param));
168  int _EXFUN(pthread_setschedparam,
169  (pthread_t thread, int policy, struct sched_param *param));
170 
171 #endif /* defined(_POSIX_THREAD_PRIORITY_SCHEDULING) */
172 
173 #if defined(_POSIX_THREAD_PRIO_INHERIT) || defined(_POSIX_THREAD_PRIO_PROTECT)
174 
175  /* Mutex Initialization Scheduling Attributes, P1003.1c/Draft 10, p. 128 */
176 
177  int _EXFUN(pthread_mutexattr_setprotocol,
178  (pthread_mutexattr_t *attr, int protocol));
179  int _EXFUN(pthread_mutexattr_getprotocol,
180  (const pthread_mutexattr_t *attr, int *protocol));
181  int _EXFUN(pthread_mutexattr_setprioceiling,
182  (pthread_mutexattr_t *attr, int prioceiling));
183  int _EXFUN(pthread_mutexattr_getprioceiling,
184  (const pthread_mutexattr_t *attr, int *prioceiling));
185 
186 #endif /* _POSIX_THREAD_PRIO_INHERIT || _POSIX_THREAD_PRIO_PROTECT */
187 
188 #if defined(_POSIX_THREAD_PRIO_PROTECT)
189 
190  /* Change the Priority Ceiling of a Mutex, P1003.1c/Draft 10, p. 131 */
191 
192  int _EXFUN(pthread_mutex_setprioceiling,
193  (pthread_mutex_t *mutex, int prioceiling, int *old_ceiling));
194  int _EXFUN(pthread_mutex_getprioceiling,
195  (pthread_mutex_t *mutex, int *prioceiling));
196 
197 #endif /* _POSIX_THREAD_PRIO_PROTECT */
198 
199  /* Thread Creation Attributes, P1003.1c/Draft 10, p, 140 */
200 
201  int _EXFUN(pthread_attr_init, (pthread_attr_t *attr));
202  int _EXFUN(pthread_attr_destroy, (pthread_attr_t *attr));
203  int _EXFUN(pthread_attr_getstacksize,
204  (const pthread_attr_t *attr, size_t *stacksize));
205  int _EXFUN(pthread_attr_setstacksize,
206  (pthread_attr_t *attr, size_t stacksize));
207  int _EXFUN(pthread_attr_getstackaddr,
208  (const pthread_attr_t *attr, void **stackaddr));
209  int _EXFUN(pthread_attr_setstackaddr,
210  (pthread_attr_t *attr, void *stackaddr));
211  int _EXFUN(pthread_attr_getdetachstate,
212  (const pthread_attr_t *attr, int *detachstate));
213  int _EXFUN(pthread_attr_setdetachstate,
214  (pthread_attr_t *attr, int detachstate));
215 
216  /* Thread Creation, P1003.1c/Draft 10, p. 144 */
217 
218  int _EXFUN(pthread_create,
219  (pthread_t *thread, const pthread_attr_t *attr,
220  void * (*start_routine)(void *), void *arg));
221 
222  /* Wait for Thread Termination, P1003.1c/Draft 10, p. 147 */
223 
224  int _EXFUN(pthread_join, (pthread_t thread, void **value_ptr));
225 
226  /* Detaching a Thread, P1003.1c/Draft 10, p. 149 */
227 
228  int _EXFUN(pthread_detach, (pthread_t thread));
229 
230  /* Thread Termination, p1003.1c/Draft 10, p. 150 */
231 
232  void _EXFUN(pthread_exit, (void *value_ptr));
233 
234  /* Get Calling Thread's ID, p1003.1c/Draft 10, p. XXX */
235 
236  pthread_t _EXFUN(pthread_self, (void));
237 
238  /* Compare Thread IDs, p1003.1c/Draft 10, p. 153 */
239 
240  int _EXFUN(pthread_equal, (pthread_t t1, pthread_t t2));
241 
242  /* Dynamic Package Initialization */
243 
244  /* This is used to statically initialize a pthread_once_t. Example:
245 
246  pthread_once_t once = PTHREAD_ONCE_INIT;
247 
248  NOTE: This is named inconsistently -- it should be INITIALIZER. */
249 
250 #define PTHREAD_ONCE_INIT { 1, 0 } /* is initialized and not run */
251 
252  int _EXFUN(pthread_once,
253  (pthread_once_t *once_control, void (*init_routine)(void)));
254 
255  /* Thread-Specific Data Key Create, P1003.1c/Draft 10, p. 163 */
256 
257  int _EXFUN(pthread_key_create,
258  (pthread_key_t *key, void (*destructor)(void *)));
259 
260  /* Thread-Specific Data Management, P1003.1c/Draft 10, p. 165 */
261 
262  int _EXFUN(pthread_setspecific, (pthread_key_t key, const void *value));
263  void * _EXFUN(pthread_getspecific, (pthread_key_t key));
264 
265  /* Thread-Specific Data Key Deletion, P1003.1c/Draft 10, p. 167 */
266 
267  int _EXFUN(pthread_key_delete, (pthread_key_t key));
268 
269  /* Execution of a Thread, P1003.1c/Draft 10, p. 181 */
270 
271 #define PTHREAD_CANCEL_ENABLE 0
272 #define PTHREAD_CANCEL_DISABLE 1
273 
274 #define PTHREAD_CANCEL_DEFERRED 0
275 #define PTHREAD_CANCEL_ASYNCHRONOUS 1
276 
277 #define PTHREAD_CANCELED ((void *) -1)
278 
279  int _EXFUN(pthread_cancel, (pthread_t thread));
280 
281  /* Setting Cancelability State, P1003.1c/Draft 10, p. 183 */
282 
283  int _EXFUN(pthread_setcancelstate, (int state, int *oldstate));
284  int _EXFUN(pthread_setcanceltype, (int type, int *oldtype));
285  void _EXFUN(pthread_testcancel, (void));
286 
287  /* Establishing Cancellation Handlers, P1003.1c/Draft 10, p. 184 */
288 
289  void _EXFUN(pthread_cleanup_push, (void (*routine)(void *), void *arg));
290  void _EXFUN(pthread_cleanup_pop, (int execute));
291 
292 #if defined(_POSIX_THREAD_CPUTIME)
293 
294  /* Accessing a Thread CPU-time Clock, P1003.4b/D8, p. 58 */
295 
296  int _EXFUN(pthread_getcpuclockid,
297  (pthread_t thread_id, clockid_t *clock_id));
298 
299  /* CPU-time Clock Thread Creation Attribute, P1003.4b/D8, p. 59 */
300 
301  int _EXFUN(pthread_attr_setcputime,
302  (pthread_attr_t *attr, int clock_allowed));
303 
304  int _EXFUN(pthread_attr_getcputime,
305  (pthread_attr_t *attr, int *clock_allowed));
306 
307 #endif /* defined(_POSIX_THREAD_CPUTIME) */
308 
309 #endif /* defined(_POSIX_THREADS) */
310 
311 #ifdef __cplusplus
312 }
313 #endif
314 
315 #endif
316 /** \endcond */
317 /* end of include file */
kthread_key_t pthread_key_t
POSIX thread data key.
Definition: sched.h:74
Object type backing kthread_once.
Definition: once.h:34
Scheduling Parameters, P1003.1b-1993, p. 249.
Definition: sched.h:23
POSIX mutex attributes.
Definition: sched.h:42
Basic sys/sched.h file for newlib.
Condition variable.
Definition: cond.h:61
Mutual exclusion lock type.
Definition: mutex.h:70
Basic sys/_pthread.h file for newlib.
Structure describing one running thread.
Definition: thread.h:90
POSIX thread attributes.
Definition: sched.h:62
POSIX condition variable attributes.
Definition: sched.h:52