git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Demo/FreeRTOS_Plus_POSIX_with_actor_Windows_Simulator/lib/include/FreeRTOS_POSIX/semaphore.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 semaphore.h\r
  28  * @brief Semaphores.\r
  29  *\r
  30  * http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/semaphore.h.html\r
  31  */\r
  32 \r
  33 #ifndef _FREERTOS_POSIX_SEMAPHORE_H_\r
  34 #define _FREERTOS_POSIX_SEMAPHORE_H_\r
  35 \r
  36 /* FreeRTOS+POSIX includes. */\r
  37 #include "FreeRTOS_POSIX/time.h"\r
  38 #include "FreeRTOS_POSIX_types.h"\r
  39 \r
  40 /**\r
  41  * @brief Semaphore type.\r
  42  */\r
  43 typedef PosixSemType_t sem_t;\r
  44 \r
  45 /**\r
  46  * @brief Destroy an unnamed semaphore.\r
  47  *\r
  48  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_destroy.html\r
  49  *\r
  50  * @retval 0 - upon successful completion\r
  51  *\r
  52  * @note Semaphore is destroyed regardless of whether there is any thread currently blocked on this semaphore.\r
  53  */\r
  54 int sem_destroy( sem_t * sem );\r
  55 \r
  56 /**\r
  57  * @brief Get the value of a semaphore.\r
  58  *\r
  59  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_getvalue.html\r
  60  *\r
  61  * @retval 0 - Upon successful completion\r
  62  *\r
  63  * @note If sem is locked, then the object to which sval points is set to zero.\r
  64  */\r
  65 int sem_getvalue( sem_t * sem,\r
  66                   int * sval );\r
  67 \r
  68 /**\r
  69  * @brief Initialize an unnamed semaphore.\r
  70  *\r
  71  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_init.html\r
  72  *\r
  73  * @note pshared is ignored. Semaphores will always be considered "shared".\r
  74  *\r
  75  * @retval 0 - upon successful completion\r
  76  * @retval -1 - otherwise. System error variable errno is also set in this case.\r
  77  *\r
  78  * @sideeffect Possible errno values\r
  79  * <br>\r
  80  * EINVAL -  The value argument exceeds {SEM_VALUE_MAX}.\r
  81  * <br>\r
  82  * ENOSPC - A resource required to initialize the semaphore has been exhausted.\r
  83  */\r
  84 int sem_init( sem_t * sem,\r
  85               int pshared,\r
  86               unsigned value );\r
  87 \r
  88 /**\r
  89  * @brief Unlock a semaphore.\r
  90  *\r
  91  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_post.html\r
  92  *\r
  93  * @retval 0 - upon successful completion\r
  94  */\r
  95 int sem_post( sem_t * sem );\r
  96 \r
  97 /**\r
  98  * @brief Lock a semaphore with timeout.\r
  99  *\r
 100  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_timedwait.html\r
 101  *\r
 102  * @retval 0 - upon successful completion\r
 103  * @retval -1 - otherwise. System error variable errno is also set in this case.\r
 104  *\r
 105  * @sideeffect Possible errno values\r
 106  * <br>\r
 107  * EINVAL - parameter specified a nanoseconds field value less than zero or greater\r
 108  * than or equal to 1000 million\r
 109  * <br>\r
 110  * ETIMEDOUT - The semaphore could not be locked before the specified timeout expired.\r
 111  *\r
 112  * @note Deadlock detection is not implemented.\r
 113  */\r
 114 int sem_timedwait( sem_t * sem,\r
 115                    const struct timespec * abstime );\r
 116 \r
 117 /**\r
 118  * @brief Lock a semaphore if available.\r
 119  *\r
 120  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_trywait.html\r
 121  *\r
 122  * @retval 0 - upon successful completion\r
 123  * @retval -1 - otherwise. System error variable errno is also set in this case.\r
 124  *\r
 125  * @sideeffect Possible errno values\r
 126  * <br>\r
 127  * EAGAIN - The semaphore was already locked, so it cannot be immediately locked by the sem_trywait() operation.\r
 128  */\r
 129 int sem_trywait( sem_t * sem );\r
 130 \r
 131 /**\r
 132  * @brief Lock a semaphore.\r
 133  *\r
 134  * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_wait.html\r
 135  *\r
 136  * @retval 0 - upon successful completion\r
 137  * @retval -1 - otherwise. System error variable errno is also set in this case.\r
 138  *\r
 139  * @note Deadlock detection is not implemented.\r
 140  */\r
 141 int sem_wait( sem_t * sem );\r
 142 \r
 143 #endif /* ifndef _FREERTOS_POSIX_SEMAPHORE_H_ */\r