]> git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Demo/FreeRTOS_Plus_POSIX_with_actor_Windows_Simulator/lib/include/FreeRTOS_POSIX/pthread.h
Add the Labs projects provided in the V10.2.1_191129 zip file.
[freertos] / FreeRTOS-Labs / Demo / FreeRTOS_Plus_POSIX_with_actor_Windows_Simulator / lib / include / FreeRTOS_POSIX / pthread.h
1 /*\r
2  * Amazon FreeRTOS POSIX V1.1.0\r
3  * Copyright (C) 2019 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
4  *\r
5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
6  * this software and associated documentation files (the "Software"), to deal in\r
7  * the Software without restriction, including without limitation the rights to\r
8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
10  * subject to the following conditions:\r
11  *\r
12  * The above copyright notice and this permission notice shall be included in all\r
13  * copies or substantial portions of the Software.\r
14  *\r
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
21  *\r
22  * http://aws.amazon.com/freertos\r
23  * http://www.FreeRTOS.org\r
24  */\r
25 \r
26 /**\r
27  * @file pthread.h\r
28  * @brief Threads.\r
29  *\r
30  * http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pthread.h.html\r
31  */\r
32 \r
33 #ifndef _FREERTOS_POSIX_PTHREAD_H_\r
34 #define _FREERTOS_POSIX_PTHREAD_H_\r
35 \r
36 /* FreeRTOS+POSIX includes. POSIX states that this header shall make symbols\r
37  * defined in sched.h and time.h visible. */\r
38 #include "FreeRTOS_POSIX/sched.h"\r
39 #include "FreeRTOS_POSIX/time.h"\r
40 \r
41 /**\r
42  * @name pthread detach state.\r
43  */\r
44 /**@{ */\r
45 #define PTHREAD_CREATE_DETACHED    0       /**< Detached. */\r
46 #define PTHREAD_CREATE_JOINABLE    1       /**< Joinable (default). */\r
47 /**@} */\r
48 \r
49 /**\r
50  * @name Returned to a single thread after a successful pthread_barrier_wait.\r
51  *\r
52  * @brief POSIX specifies that "The constant PTHREAD_BARRIER_SERIAL_THREAD is defined in\r
53  * <pthread.h> and its value shall be distinct from any other value returned by pthread_barrier_wait()."\r
54  * So it's defined as negative to distinguish it from the errnos, which are positive.\r
55  */\r
56 #define PTHREAD_BARRIER_SERIAL_THREAD    ( -2 )\r
57 \r
58 /**\r
59  * @name Mutex types.\r
60  */\r
61 /**@{ */\r
62 #ifndef PTHREAD_MUTEX_NORMAL\r
63     #define PTHREAD_MUTEX_NORMAL        0                        /**< Non-robust, deadlock on relock, does not remember owner. */\r
64 #endif\r
65 #ifndef PTHREAD_MUTEX_ERRORCHECK\r
66     #define PTHREAD_MUTEX_ERRORCHECK    1                        /**< Non-robust, error on relock,  remembers owner. */\r
67 #endif\r
68 #ifndef PTHREAD_MUTEX_RECURSIVE\r
69     #define PTHREAD_MUTEX_RECURSIVE     2                        /**< Non-robust, recursive relock, remembers owner. */\r
70 #endif\r
71 #ifndef PTHREAD_MUTEX_DEFAULT\r
72     #define PTHREAD_MUTEX_DEFAULT       PTHREAD_MUTEX_NORMAL     /**< PTHREAD_MUTEX_NORMAL (default). */\r
73 #endif\r
74 /**@} */\r
75 \r
76 /**\r
77  * @name Compile-time initializers.\r
78  *\r
79  * @brief To use PTHREAD_COND_INITIALIZER, posixconfigENABLE_PTHREAD_COND_T needs to be set to 1\r
80  * in port specific POSIX config file.\r
81  *\r
82  * To use PTHREAD_MUTEX_INITIALIZER, posixconfigENABLE_PTHREAD_MUTEX_T needs to be set to 1 in\r
83  * port specific POSIX config file.\r
84  */\r
85 /**@{ */\r
86 #if posixconfigENABLE_PTHREAD_COND_T == 1\r
87     #define PTHREAD_COND_INITIALIZER    FREERTOS_POSIX_COND_INITIALIZER       /**< pthread_cond_t. */\r
88 #endif\r
89 \r
90 #if posixconfigENABLE_PTHREAD_MUTEX_T == 1\r
91     #define PTHREAD_MUTEX_INITIALIZER    FREERTOS_POSIX_MUTEX_INITIALIZER /**< pthread_mutex_t. */\r
92 #endif\r
93 \r
94 /**@} */\r
95 \r
96 /**\r
97  * @brief Destroy the thread attributes object.\r
98  *\r
99  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_destroy.html\r
100  *\r
101  * @retval 0 - Upon successful completion.\r
102  */\r
103 int pthread_attr_destroy( pthread_attr_t * attr );\r
104 \r
105 /**\r
106  * @brief Get detachstate attribute.\r
107  *\r
108  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_getdetachstate.html\r
109  *\r
110  * @retval 0 - Upon successful completion.\r
111  */\r
112 int pthread_attr_getdetachstate( const pthread_attr_t * attr,\r
113                                  int * detachstate );\r
114 \r
115 /**\r
116  * @brief Get schedparam attribute.\r
117  *\r
118  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_getschedparam.html\r
119  *\r
120  * @retval 0 - Upon successful completion.\r
121  */\r
122 int pthread_attr_getschedparam( const pthread_attr_t * attr,\r
123                                 struct sched_param * param );\r
124 \r
125 /**\r
126  * @brief Get stacksize attribute.\r
127  *\r
128  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_getstacksize.html\r
129  *\r
130  * @retval 0 - Upon successful completion.\r
131  */\r
132 int pthread_attr_getstacksize( const pthread_attr_t * attr,\r
133                                size_t * stacksize );\r
134 \r
135 /**\r
136  * @brief Initialize the thread attributes object.\r
137  *\r
138  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_init.html\r
139  *\r
140  * @retval 0 - Upon successful completion.\r
141  *\r
142  * @note Currently, only stack size, sched_param, and detach state attributes\r
143  * are supported. Also see pthread_attr_get*() and pthread_attr_set*().\r
144  */\r
145 int pthread_attr_init( pthread_attr_t * attr );\r
146 \r
147 /**\r
148  * @brief Set detachstate attribute.\r
149  *\r
150  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_setdetachstate.html\r
151  *\r
152  * @retval 0 - Upon successful completion\r
153  * @retval EINVAL - The value of detachstate is not valid. Currently, supported detach states are --\r
154  *                  PTHREAD_CREATE_DETACHED and PTHREAD_CREATE_JOINABLE.\r
155  */\r
156 int pthread_attr_setdetachstate( pthread_attr_t * attr,\r
157                                  int detachstate );\r
158 \r
159 /**\r
160  * @brief Set schedparam attribute.\r
161  *\r
162  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_setschedparam.html\r
163  *\r
164  * @retval 0 - Upon successful completion.\r
165  * @retval EINVAL - The value of param is not valid.\r
166  * @retval ENOTSUP - An attempt was made to set the attribute to an unsupported value.\r
167  */\r
168 int pthread_attr_setschedparam( pthread_attr_t * attr,\r
169                                 const struct sched_param * param );\r
170 \r
171 /**\r
172  * @brief Set the schedpolicy attribute.\r
173  *\r
174  * http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_setschedpolicy.html\r
175  *\r
176  * @retval 0 - Upon successful completion.\r
177  *\r
178  * @warning This function is a stub and always returns 0.\r
179  */\r
180 int pthread_attr_setschedpolicy( pthread_attr_t * attr,\r
181                                  int policy );\r
182 \r
183 /**\r
184  * @brief Set stacksize attribute.\r
185  *\r
186  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_setstacksize.html\r
187  *\r
188  * @retval 0 - Upon successful completion.\r
189  * @retval EINVAL - The value of stacksize is less than {PTHREAD_STACK_MIN}.\r
190  */\r
191 int pthread_attr_setstacksize( pthread_attr_t * attr,\r
192                                size_t stacksize );\r
193 \r
194 /**\r
195  * @brief Destroy a barrier object.\r
196  *\r
197  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_barrier_destroy.html\r
198  *\r
199  * @retval 0 - Upon successful completion.\r
200  *\r
201  * @note This function does not validate whether there is any thread blocking on the barrier before destroying.\r
202  */\r
203 int pthread_barrier_destroy( pthread_barrier_t * barrier );\r
204 \r
205 /**\r
206  * @brief Initialize a barrier object.\r
207  *\r
208  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_barrier_init.html\r
209  *\r
210  * @retval 0 - Upon successful completion.\r
211  * @retval EINVAL - The value specified by count is equal to zero.\r
212  * @retval ENOMEM - count cannot fit into FreeRTOS event group type OR insufficient memory exists to initialize the barrier.\r
213  *\r
214  * @note attr is ignored.\r
215  *\r
216  * @note pthread_barrier_init() is implemented with FreeRTOS event group.\r
217  * To ensure count fits in event group, count may be at most 8 when configUSE_16_BIT_TICKS is 1;\r
218  * it may be at most 24 otherwise. configUSE_16_BIT_TICKS is configured in application FreeRTOSConfig.h\r
219  * file, which defines how many bits tick count type has. See further details and limitation about event\r
220  * group and configUSE_16_BIT_TICKS in FreeRTOS site.\r
221  */\r
222 int pthread_barrier_init( pthread_barrier_t * barrier,\r
223                           const pthread_barrierattr_t * attr,\r
224                           unsigned count );\r
225 \r
226 /**\r
227  * @brief Synchronize at a barrier.\r
228  *\r
229  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_barrier_wait.html\r
230  *\r
231  * @retval PTHREAD_BARRIER_SERIAL_THREAD - Upon successful completion, the first thread.\r
232  * @retval 0 - Upon successful completion, other thread(s).\r
233  */\r
234 int pthread_barrier_wait( pthread_barrier_t * barrier );\r
235 \r
236 /**\r
237  * @brief Thread creation.\r
238  *\r
239  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_create.html\r
240  *\r
241  * @retval 0 - Upon successful completion.\r
242  * @retval EAGAIN - Insufficient memory for either thread structure or task creation.\r
243  */\r
244 int pthread_create( pthread_t * thread,\r
245                     const pthread_attr_t * attr,\r
246                     void *( *startroutine )( void * ),\r
247                     void * arg );\r
248 \r
249 /**\r
250  * @brief Broadcast a condition.\r
251  *\r
252  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_broadcast.html\r
253  *\r
254  * @retval 0 - Upon successful completion.\r
255  */\r
256 int pthread_cond_broadcast( pthread_cond_t * cond );\r
257 \r
258 /**\r
259  * @brief Destroy condition variables.\r
260  *\r
261  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_destroy.html\r
262  *\r
263  * @retval 0 - Upon successful completion.\r
264  */\r
265 int pthread_cond_destroy( pthread_cond_t * cond );\r
266 \r
267 /**\r
268  * @brief Initialize condition variables.\r
269  *\r
270  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_init.html\r
271  *\r
272  * @retval 0 - Upon successful completion.\r
273  * @retval ENOMEM - Insufficient memory exists to initialize the condition variable.\r
274  *\r
275  * @note attr is ignored and treated as NULL. Default setting is always used.\r
276  */\r
277 int pthread_cond_init( pthread_cond_t * cond,\r
278                        const pthread_condattr_t * attr );\r
279 \r
280 /**\r
281  * @brief Signal a condition.\r
282  *\r
283  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_signal.html\r
284  *\r
285  * @retval 0 - Upon successful completion.\r
286  */\r
287 int pthread_cond_signal( pthread_cond_t * cond );\r
288 \r
289 /**\r
290  * @brief Wait on a condition with a timeout.\r
291  *\r
292  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_timedwait.html\r
293  *\r
294  * @retval 0 - Upon successful completion.\r
295  * @retval EINVAL - The abstime argument passed in does not refer to an initialized structure OR\r
296  *                  the abstime parameter specified a nanoseconds field value less than zero or\r
297  *                  greater than or equal to 1000 million.\r
298  * @retval ETIMEDOUT - The time specified by abstime to pthread_cond_timedwait() has passed.\r
299  */\r
300 int pthread_cond_timedwait( pthread_cond_t * cond,\r
301                             pthread_mutex_t * mutex,\r
302                             const struct timespec * abstime );\r
303 \r
304 /**\r
305  * @brief Wait on a condition.\r
306  *\r
307  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_wait.html\r
308  *\r
309  * @retval 0 - Upon successful completion.\r
310  */\r
311 int pthread_cond_wait( pthread_cond_t * cond,\r
312                        pthread_mutex_t * mutex );\r
313 \r
314 /**\r
315  * @brief Compare thread IDs.\r
316  *\r
317  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_equal.html\r
318  *\r
319  * @retval 0 - t1 and t2 are both not NULL && equal.\r
320  * @retval non-zero - otherwise.\r
321  */\r
322 int pthread_equal( pthread_t t1,\r
323                    pthread_t t2 );\r
324 \r
325 /**\r
326  * @brief Thread termination.\r
327  *\r
328  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_exit.html\r
329  *\r
330  * @retval void - this function cannot return to its caller.\r
331  */\r
332 void pthread_exit( void * value_ptr );\r
333 \r
334 /**\r
335  * @brief Dynamic thread scheduling parameters access.\r
336  *\r
337  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_getschedparam.html\r
338  *\r
339  * @retval 0 - Upon successful completion.\r
340  *\r
341  * @note policy is always set to SCHED_OTHER by this function.\r
342  */\r
343 int pthread_getschedparam( pthread_t thread,\r
344                            int * policy,\r
345                            struct sched_param * param );\r
346 \r
347 /**\r
348  * @brief Wait for thread termination.\r
349  *\r
350  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_join.html\r
351  *\r
352  * @retval 0 - Upon successful completion.\r
353  * @retval EDEADLK - The value specified by the thread argument to pthread_join() does not refer\r
354  *                   to a joinable thread OR multiple simultaneous calls to pthread_join()\r
355  *                   specifying the same target thread OR the value specified by the thread argument\r
356  *                   to pthread_join() refers to the calling thread.\r
357  */\r
358 int pthread_join( pthread_t thread,\r
359                   void ** retval );\r
360 \r
361 /**\r
362  * @brief Destroy a mutex.\r
363  *\r
364  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_destroy.html\r
365  *\r
366  * @retval 0 - Upon successful completion.\r
367  *\r
368  * @note If there exists a thread holding this mutex, this function returns 0 with mutex not being destroyed.\r
369  */\r
370 int pthread_mutex_destroy( pthread_mutex_t * mutex );\r
371 \r
372 /**\r
373  * @brief Initialize a mutex.\r
374  *\r
375  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_init.html\r
376  *\r
377  * @retval 0 - Upon successful completion.\r
378  * @retval ENOMEM - Insufficient memory exists to initialize the mutex structure.\r
379  * @retval EAGAIN - Unable to initialize the mutex structure member(s).\r
380  */\r
381 int pthread_mutex_init( pthread_mutex_t * mutex,\r
382                         const pthread_mutexattr_t * attr );\r
383 \r
384 /**\r
385  * @brief Lock a mutex.\r
386  *\r
387  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_lock.html\r
388  *\r
389  * @retval 0 - Upon successful completion.\r
390  * @retval EINVAL - the abstime parameter specified a nanoseconds field value less than zero\r
391  *                  or greater than or equal to 1000 million.\r
392  * @retval EDEADLK - The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current thread already\r
393  *                   owns the mutex.\r
394  */\r
395 int pthread_mutex_lock( pthread_mutex_t * mutex );\r
396 \r
397 /**\r
398  * @brief Lock a mutex with timeout.\r
399  *\r
400  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_timedlock.html\r
401  *\r
402  * @retval 0 - Upon successful completion.\r
403  * @retval EINVAL - The abstime argument passed in does not refer to an initialized structure OR\r
404  *                  the abstime parameter specified a nanoseconds field value less than zero or\r
405  *                  greater than or equal to 1000 million.\r
406  * @retval EDEADLK - The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current thread already owns the mutex.\r
407  * @retval ETIMEDOUT - The mutex could not be locked before the specified timeout expired.\r
408  */\r
409 int pthread_mutex_timedlock( pthread_mutex_t * mutex,\r
410                              const struct timespec * abstime );\r
411 \r
412 /**\r
413  * @brief Attempt to lock a mutex. Fail immediately if mutex is already locked.\r
414  *\r
415  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_trylock.html\r
416  *\r
417  * @retval 0 - Upon successful completion.\r
418  * @retval EINVAL - the abstime parameter specified a nanoseconds field value less than zero\r
419  *                  or greater than or equal to 1000 million.\r
420  * @retval EDEADLK - The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current thread already\r
421  *                   owns the mutex.\r
422  * @retval EBUSY - The mutex could not be acquired because it was already locked.\r
423  */\r
424 int pthread_mutex_trylock( pthread_mutex_t * mutex );\r
425 \r
426 /**\r
427  * @brief Unlock a mutex.\r
428  *\r
429  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_unlock.html\r
430  *\r
431  * @retval 0 - Upon successful completion.\r
432  * @retval EPERM - The mutex type is PTHREAD_MUTEX_ERRORCHECK or PTHREAD_MUTEX_RECURSIVE, and\r
433  *                 the current thread does not own the mutex.\r
434  */\r
435 int pthread_mutex_unlock( pthread_mutex_t * mutex );\r
436 \r
437 /**\r
438  * @brief Destroy the mutex attributes object.\r
439  *\r
440  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutexattr_destroy.html\r
441  *\r
442  * @retval 0 - Upon successful completion.\r
443  */\r
444 int pthread_mutexattr_destroy( pthread_mutexattr_t * attr );\r
445 \r
446 /**\r
447  * @brief Get the mutex type attribute.\r
448  *\r
449  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutexattr_gettype.html\r
450  *\r
451  * @retval 0 - Upon successful completion.\r
452  */\r
453 int pthread_mutexattr_gettype( const pthread_mutexattr_t * attr,\r
454                                int * type );\r
455 \r
456 /**\r
457  * @brief Initialize the mutex attributes object.\r
458  *\r
459  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutexattr_init.html\r
460  *\r
461  * @retval 0 - Upon successful completion.\r
462  *\r
463  * @note Currently, only the type attribute is supported. Also see pthread_mutexattr_settype()\r
464  *       and pthread_mutexattr_gettype().\r
465  */\r
466 int pthread_mutexattr_init( pthread_mutexattr_t * attr );\r
467 \r
468 /**\r
469  * @brief Set the mutex type attribute.\r
470  *\r
471  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutexattr_settype.html\r
472  *\r
473  * @retval 0 - Upon successful completion.\r
474  * @retval EINVAL - The value type is invalid.\r
475  */\r
476 int pthread_mutexattr_settype( pthread_mutexattr_t * attr,\r
477                                int type );\r
478 \r
479 /**\r
480  * @brief Get the calling thread ID.\r
481  *\r
482  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_self.html\r
483  *\r
484  * @retval the thread ID of the calling thread.\r
485  */\r
486 pthread_t pthread_self( void );\r
487 \r
488 /**\r
489  * @brief Dynamic thread scheduling parameters access.\r
490  *\r
491  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_setschedparam.html\r
492  *\r
493  * @note policy is ignored; only priority (param.sched_priority) may be changed.\r
494  *\r
495  * @retval 0 - Upon successful completion.\r
496  */\r
497 int pthread_setschedparam( pthread_t thread,\r
498                            int policy,\r
499                            const struct sched_param * param );\r
500 \r
501 #endif /* _FREERTOS_POSIX_PTHREAD_H_ */\r