2 * Amazon FreeRTOS POSIX V1.1.0
\r
3 * Copyright (C) 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
\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
12 * The above copyright notice and this permission notice shall be included in all
\r
13 * copies or substantial portions of the Software.
\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
22 * http://aws.amazon.com/freertos
\r
23 * http://www.FreeRTOS.org
\r
30 * http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pthread.h.html
\r
33 #ifndef _FREERTOS_POSIX_PTHREAD_H_
\r
34 #define _FREERTOS_POSIX_PTHREAD_H_
\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
42 * @name pthread detach state.
\r
45 #define PTHREAD_CREATE_DETACHED 0 /**< Detached. */
\r
46 #define PTHREAD_CREATE_JOINABLE 1 /**< Joinable (default). */
\r
50 * @name Returned to a single thread after a successful pthread_barrier_wait.
\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
56 #define PTHREAD_BARRIER_SERIAL_THREAD ( -2 )
\r
59 * @name Mutex types.
\r
62 #ifndef PTHREAD_MUTEX_NORMAL
\r
63 #define PTHREAD_MUTEX_NORMAL 0 /**< Non-robust, deadlock on relock, does not remember owner. */
\r
65 #ifndef PTHREAD_MUTEX_ERRORCHECK
\r
66 #define PTHREAD_MUTEX_ERRORCHECK 1 /**< Non-robust, error on relock, remembers owner. */
\r
68 #ifndef PTHREAD_MUTEX_RECURSIVE
\r
69 #define PTHREAD_MUTEX_RECURSIVE 2 /**< Non-robust, recursive relock, remembers owner. */
\r
71 #ifndef PTHREAD_MUTEX_DEFAULT
\r
72 #define PTHREAD_MUTEX_DEFAULT PTHREAD_MUTEX_NORMAL /**< PTHREAD_MUTEX_NORMAL (default). */
\r
77 * @name Compile-time initializers.
\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
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
86 #if posixconfigENABLE_PTHREAD_COND_T == 1
\r
87 #define PTHREAD_COND_INITIALIZER FREERTOS_POSIX_COND_INITIALIZER /**< pthread_cond_t. */
\r
90 #if posixconfigENABLE_PTHREAD_MUTEX_T == 1
\r
91 #define PTHREAD_MUTEX_INITIALIZER FREERTOS_POSIX_MUTEX_INITIALIZER /**< pthread_mutex_t. */
\r
97 * @brief Destroy the thread attributes object.
\r
99 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_destroy.html
\r
101 * @retval 0 - Upon successful completion.
\r
103 int pthread_attr_destroy( pthread_attr_t * attr );
\r
106 * @brief Get detachstate attribute.
\r
108 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_getdetachstate.html
\r
110 * @retval 0 - Upon successful completion.
\r
112 int pthread_attr_getdetachstate( const pthread_attr_t * attr,
\r
113 int * detachstate );
\r
116 * @brief Get schedparam attribute.
\r
118 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_getschedparam.html
\r
120 * @retval 0 - Upon successful completion.
\r
122 int pthread_attr_getschedparam( const pthread_attr_t * attr,
\r
123 struct sched_param * param );
\r
126 * @brief Get stacksize attribute.
\r
128 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_getstacksize.html
\r
130 * @retval 0 - Upon successful completion.
\r
132 int pthread_attr_getstacksize( const pthread_attr_t * attr,
\r
133 size_t * stacksize );
\r
136 * @brief Initialize the thread attributes object.
\r
138 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_init.html
\r
140 * @retval 0 - Upon successful completion.
\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
145 int pthread_attr_init( pthread_attr_t * attr );
\r
148 * @brief Set detachstate attribute.
\r
150 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_setdetachstate.html
\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
156 int pthread_attr_setdetachstate( pthread_attr_t * attr,
\r
160 * @brief Set schedparam attribute.
\r
162 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_setschedparam.html
\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
168 int pthread_attr_setschedparam( pthread_attr_t * attr,
\r
169 const struct sched_param * param );
\r
172 * @brief Set the schedpolicy attribute.
\r
174 * http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_setschedpolicy.html
\r
176 * @retval 0 - Upon successful completion.
\r
178 * @warning This function is a stub and always returns 0.
\r
180 int pthread_attr_setschedpolicy( pthread_attr_t * attr,
\r
184 * @brief Set stacksize attribute.
\r
186 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_setstacksize.html
\r
188 * @retval 0 - Upon successful completion.
\r
189 * @retval EINVAL - The value of stacksize is less than {PTHREAD_STACK_MIN}.
\r
191 int pthread_attr_setstacksize( pthread_attr_t * attr,
\r
192 size_t stacksize );
\r
195 * @brief Destroy a barrier object.
\r
197 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_barrier_destroy.html
\r
199 * @retval 0 - Upon successful completion.
\r
201 * @note This function does not validate whether there is any thread blocking on the barrier before destroying.
\r
203 int pthread_barrier_destroy( pthread_barrier_t * barrier );
\r
206 * @brief Initialize a barrier object.
\r
208 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_barrier_init.html
\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
214 * @note attr is ignored.
\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
222 int pthread_barrier_init( pthread_barrier_t * barrier,
\r
223 const pthread_barrierattr_t * attr,
\r
227 * @brief Synchronize at a barrier.
\r
229 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_barrier_wait.html
\r
231 * @retval PTHREAD_BARRIER_SERIAL_THREAD - Upon successful completion, the first thread.
\r
232 * @retval 0 - Upon successful completion, other thread(s).
\r
234 int pthread_barrier_wait( pthread_barrier_t * barrier );
\r
237 * @brief Thread creation.
\r
239 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_create.html
\r
241 * @retval 0 - Upon successful completion.
\r
242 * @retval EAGAIN - Insufficient memory for either thread structure or task creation.
\r
244 int pthread_create( pthread_t * thread,
\r
245 const pthread_attr_t * attr,
\r
246 void *( *startroutine )( void * ),
\r
250 * @brief Broadcast a condition.
\r
252 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_broadcast.html
\r
254 * @retval 0 - Upon successful completion.
\r
256 int pthread_cond_broadcast( pthread_cond_t * cond );
\r
259 * @brief Destroy condition variables.
\r
261 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_destroy.html
\r
263 * @retval 0 - Upon successful completion.
\r
265 int pthread_cond_destroy( pthread_cond_t * cond );
\r
268 * @brief Initialize condition variables.
\r
270 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_init.html
\r
272 * @retval 0 - Upon successful completion.
\r
273 * @retval ENOMEM - Insufficient memory exists to initialize the condition variable.
\r
275 * @note attr is ignored and treated as NULL. Default setting is always used.
\r
277 int pthread_cond_init( pthread_cond_t * cond,
\r
278 const pthread_condattr_t * attr );
\r
281 * @brief Signal a condition.
\r
283 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_signal.html
\r
285 * @retval 0 - Upon successful completion.
\r
287 int pthread_cond_signal( pthread_cond_t * cond );
\r
290 * @brief Wait on a condition with a timeout.
\r
292 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_timedwait.html
\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
300 int pthread_cond_timedwait( pthread_cond_t * cond,
\r
301 pthread_mutex_t * mutex,
\r
302 const struct timespec * abstime );
\r
305 * @brief Wait on a condition.
\r
307 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_wait.html
\r
309 * @retval 0 - Upon successful completion.
\r
311 int pthread_cond_wait( pthread_cond_t * cond,
\r
312 pthread_mutex_t * mutex );
\r
315 * @brief Compare thread IDs.
\r
317 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_equal.html
\r
319 * @retval 0 - t1 and t2 are both not NULL && equal.
\r
320 * @retval non-zero - otherwise.
\r
322 int pthread_equal( pthread_t t1,
\r
326 * @brief Thread termination.
\r
328 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_exit.html
\r
330 * @retval void - this function cannot return to its caller.
\r
332 void pthread_exit( void * value_ptr );
\r
335 * @brief Dynamic thread scheduling parameters access.
\r
337 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_getschedparam.html
\r
339 * @retval 0 - Upon successful completion.
\r
341 * @note policy is always set to SCHED_OTHER by this function.
\r
343 int pthread_getschedparam( pthread_t thread,
\r
345 struct sched_param * param );
\r
348 * @brief Wait for thread termination.
\r
350 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_join.html
\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
358 int pthread_join( pthread_t thread,
\r
362 * @brief Destroy a mutex.
\r
364 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_destroy.html
\r
366 * @retval 0 - Upon successful completion.
\r
368 * @note If there exists a thread holding this mutex, this function returns 0 with mutex not being destroyed.
\r
370 int pthread_mutex_destroy( pthread_mutex_t * mutex );
\r
373 * @brief Initialize a mutex.
\r
375 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_init.html
\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
381 int pthread_mutex_init( pthread_mutex_t * mutex,
\r
382 const pthread_mutexattr_t * attr );
\r
385 * @brief Lock a mutex.
\r
387 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_lock.html
\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
395 int pthread_mutex_lock( pthread_mutex_t * mutex );
\r
398 * @brief Lock a mutex with timeout.
\r
400 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_timedlock.html
\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
409 int pthread_mutex_timedlock( pthread_mutex_t * mutex,
\r
410 const struct timespec * abstime );
\r
413 * @brief Attempt to lock a mutex. Fail immediately if mutex is already locked.
\r
415 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_trylock.html
\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
422 * @retval EBUSY - The mutex could not be acquired because it was already locked.
\r
424 int pthread_mutex_trylock( pthread_mutex_t * mutex );
\r
427 * @brief Unlock a mutex.
\r
429 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_unlock.html
\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
435 int pthread_mutex_unlock( pthread_mutex_t * mutex );
\r
438 * @brief Destroy the mutex attributes object.
\r
440 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutexattr_destroy.html
\r
442 * @retval 0 - Upon successful completion.
\r
444 int pthread_mutexattr_destroy( pthread_mutexattr_t * attr );
\r
447 * @brief Get the mutex type attribute.
\r
449 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutexattr_gettype.html
\r
451 * @retval 0 - Upon successful completion.
\r
453 int pthread_mutexattr_gettype( const pthread_mutexattr_t * attr,
\r
457 * @brief Initialize the mutex attributes object.
\r
459 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutexattr_init.html
\r
461 * @retval 0 - Upon successful completion.
\r
463 * @note Currently, only the type attribute is supported. Also see pthread_mutexattr_settype()
\r
464 * and pthread_mutexattr_gettype().
\r
466 int pthread_mutexattr_init( pthread_mutexattr_t * attr );
\r
469 * @brief Set the mutex type attribute.
\r
471 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutexattr_settype.html
\r
473 * @retval 0 - Upon successful completion.
\r
474 * @retval EINVAL - The value type is invalid.
\r
476 int pthread_mutexattr_settype( pthread_mutexattr_t * attr,
\r
480 * @brief Get the calling thread ID.
\r
482 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_self.html
\r
484 * @retval the thread ID of the calling thread.
\r
486 pthread_t pthread_self( void );
\r
489 * @brief Dynamic thread scheduling parameters access.
\r
491 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_setschedparam.html
\r
493 * @note policy is ignored; only priority (param.sched_priority) may be changed.
\r
495 * @retval 0 - Upon successful completion.
\r
497 int pthread_setschedparam( pthread_t thread,
\r
499 const struct sched_param * param );
\r
501 #endif /* _FREERTOS_POSIX_PTHREAD_H_ */
\r