git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-IoT-Libraries/abstractions/platform/include/platform/iot_threads.h

   1 /*\r
   2  * Amazon FreeRTOS Platform V1.0.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 iot_threads.h\r
  28  * @brief Threading and synchronization functions used by libraries in this SDK.\r
  29  */\r
  30 \r
  31 #ifndef IOT_THREADS_H_\r
  32 #define IOT_THREADS_H_\r
  33 \r
  34 /* The config header is always included first. */\r
  35 #include "iot_config.h"\r
  36 \r
  37 /* Standard includes. */\r
  38 #include <stdbool.h>\r
  39 #include <stdint.h>\r
  40 \r
  41 /* Platform layer types include. */\r
  42 #include "types/iot_platform_types.h"\r
  43 \r
  44 /**\r
  45  * @functionspage{platform_threads,platform thread management,Thread Management}\r
  46  * - @functionname{platform_threads_function_createdetachedthread}\r
  47  * - @functionname{platform_threads_function_mutexcreate}\r
  48  * - @functionname{platform_threads_function_mutexdestroy}\r
  49  * - @functionname{platform_threads_function_mutexlock}\r
  50  * - @functionname{platform_threads_function_mutextrylock}\r
  51  * - @functionname{platform_threads_function_mutexunlock}\r
  52  * - @functionname{platform_threads_function_semaphorecreate}\r
  53  * - @functionname{platform_threads_function_semaphoredestroy}\r
  54  * - @functionname{platform_threads_function_semaphoregetcount}\r
  55  * - @functionname{platform_threads_function_semaphorewait}\r
  56  * - @functionname{platform_threads_function_semaphoretrywait}\r
  57  * - @functionname{platform_threads_function_semaphoretimedwait}\r
  58  * - @functionname{platform_threads_function_semaphorepost}\r
  59  */\r
  60 \r
  61 /**\r
  62  * @functionpage{Iot_CreateDetachedThread,platform_threads,createdetachedthread}\r
  63  * @functionpage{IotMutex_Create,platform_threads,mutexcreate}\r
  64  * @functionpage{IotMutex_Destroy,platform_threads,mutexdestroy}\r
  65  * @functionpage{IotMutex_Lock,platform_threads,mutexlock}\r
  66  * @functionpage{IotMutex_TryLock,platform_threads,mutextrylock}\r
  67  * @functionpage{IotMutex_Unlock,platform_threads,mutexunlock}\r
  68  * @functionpage{IotSemaphore_Create,platform_threads,semaphorecreate}\r
  69  * @functionpage{IotSemaphore_Destroy,platform_threads,semaphoredestroy}\r
  70  * @functionpage{IotSemaphore_GetCount,platform_threads,semaphoregetcount}\r
  71  * @functionpage{IotSemaphore_Wait,platform_threads,semaphorewait}\r
  72  * @functionpage{IotSemaphore_TryWait,platform_threads,semaphoretrywait}\r
  73  * @functionpage{IotSemaphore_TimedWait,platform_threads,semaphoretimedwait}\r
  74  * @functionpage{IotSemaphore_Post,platform_threads,semaphorepost}\r
  75  */\r
  76 \r
  77 /**\r
  78  * @brief Create a new detached thread, i.e. a thread that cleans up after itself.\r
  79  *\r
  80  * This function creates a new thread. Threads created by this function exit\r
  81  * upon returning from the thread routine. Any resources taken must be freed\r
  82  * by the exiting thread.\r
  83  *\r
  84  * @param[in] threadRoutine The function this thread should run.\r
  85  * @param[in] pArgument The argument passed to `threadRoutine`.\r
  86  * @param[in] priority Represents the priority of the new thread, as defined by\r
  87  * the system. The value #IOT_THREAD_DEFAULT_PRIORITY (i.e. `0`) must be used to\r
  88  * represent the system default for thread priority.\r
  89  * @param[in] stackSize Represents the stack size of the new thread, as defined\r
  90  * by the system. The value #IOT_THREAD_DEFAULT_STACK_SIZE (i.e. `0`) must be used\r
  91  * to represent the system default for stack size.\r
  92  *\r
  93  * @return `true` if the new thread was successfully created; `false` otherwise.\r
  94  *\r
  95  * @code{c}\r
  96  * // Thread routine.\r
  97  * void threadRoutine( void * pArgument );\r
  98  *\r
  99  * // Run threadRoutine in a detached thread, using default priority and stack size.\r
 100  * if( Iot_CreateDetachedThread( threadRoutine,\r
 101  *                               NULL,\r
 102  *                               IOT_THREAD_DEFAULT_PRIORITY,\r
 103  *                               IOT_THREAD_DEFAULT_STACK_SIZE ) == true )\r
 104  * {\r
 105  *     // Success\r
 106  * }\r
 107  * else\r
 108  * {\r
 109  *     // Failure, no thread was created.\r
 110  * }\r
 111  * @endcode\r
 112  */\r
 113 /* @[declare_platform_threads_createdetachedthread] */\r
 114 bool Iot_CreateDetachedThread( IotThreadRoutine_t threadRoutine,\r
 115                                void * pArgument,\r
 116                                int32_t priority,\r
 117                                size_t stackSize );\r
 118 /* @[declare_platform_threads_createdetachedthread] */\r
 119 \r
 120 /**\r
 121  * @brief Create a new mutex.\r
 122  *\r
 123  * This function creates a new, unlocked mutex. It must be called on an uninitialized\r
 124  * #IotMutex_t. This function must not be called on an already-initialized #IotMutex_t.\r
 125  *\r
 126  * @param[in] pNewMutex Pointer to the memory that will hold the new mutex.\r
 127  * @param[in] recursive Set to `true` to create a recursive mutex, i.e. a mutex that\r
 128  * may be locked multiple times by the same thread. If the system does not support\r
 129  * recursive mutexes, this function should do nothing and return `false`.\r
 130  *\r
 131  * @return `true` if mutex creation succeeds; `false` otherwise.\r
 132  *\r
 133  * @see @ref platform_threads_function_mutexdestroy\r
 134  *\r
 135  * <b>Example</b>\r
 136  * @code{c}\r
 137  * IotMutex_t mutex;\r
 138  *\r
 139  * // Create non-recursive mutex.\r
 140  * if( IotMutex_Create( &mutex, false ) == true )\r
 141  * {\r
 142  *     // Lock and unlock the mutex...\r
 143  *\r
 144  *     // Destroy the mutex when it's no longer needed.\r
 145  *     IotMutex_Destroy( &mutex );\r
 146  * }\r
 147  * @endcode\r
 148  */\r
 149 /* @[declare_platform_threads_mutexcreate] */\r
 150 bool IotMutex_Create( IotMutex_t * pNewMutex, bool recursive );\r
 151 /* @[declare_platform_threads_mutexcreate] */\r
 152 \r
 153 /**\r
 154  * @brief Free resources used by a mutex.\r
 155  *\r
 156  * This function frees resources used by a mutex. It must be called on an initialized\r
 157  * #IotMutex_t. No other mutex functions should be called on `pMutex` after calling\r
 158  * this function (unless the mutex is re-created).\r
 159  *\r
 160  * @param[in] pMutex The mutex to destroy.\r
 161  *\r
 162  * @warning This function must not be called on a locked mutex.\r
 163  * @see @ref platform_threads_function_mutexcreate\r
 164  */\r
 165 /* @[declare_platform_threads_mutexdestroy] */\r
 166 void IotMutex_Destroy( IotMutex_t * pMutex );\r
 167 /* @[declare_platform_threads_mutexdestroy] */\r
 168 \r
 169 /**\r
 170  * @brief Lock a mutex. This function should only return when the mutex is locked;\r
 171  * it is not expected to fail.\r
 172  *\r
 173  * This function blocks and waits until a mutex is available. It waits forever\r
 174  * (deadlocks) if `pMutex` is already locked and never unlocked.\r
 175  *\r
 176  * @param[in] pMutex The mutex to lock.\r
 177  *\r
 178  * @see @ref platform_threads_function_mutextrylock for a nonblocking lock.\r
 179  */\r
 180 /* @[declare_platform_threads_mutexlock] */\r
 181 void IotMutex_Lock( IotMutex_t * pMutex );\r
 182 /* @[declare_platform_threads_mutexlock] */\r
 183 \r
 184 /**\r
 185  * @brief Attempt to lock a mutex. Return immediately if the mutex is not available.\r
 186  *\r
 187  * If `pMutex` is available, this function immediately locks it and returns.\r
 188  * Otherwise, this function returns without locking `pMutex`.\r
 189  *\r
 190  * @param[in] pMutex The mutex to lock.\r
 191  *\r
 192  * @return `true` if the mutex was successfully locked; `false` if the mutex was\r
 193  * not available.\r
 194  *\r
 195  * @see @ref platform_threads_function_mutexlock for a blocking lock.\r
 196  */\r
 197 /* @[declare_platform_threads_mutextrylock] */\r
 198 bool IotMutex_TryLock( IotMutex_t * pMutex );\r
 199 /* @[declare_platform_threads_mutextrylock] */\r
 200 \r
 201 /**\r
 202  * @brief Unlock a mutex. This function should only return when the mutex is unlocked;\r
 203  * it is not expected to fail.\r
 204  *\r
 205  * Unlocks a locked mutex. `pMutex` must have been locked by the thread calling\r
 206  * this function.\r
 207  *\r
 208  * @param[in] pMutex The mutex to unlock.\r
 209  *\r
 210  * @note This function should not be called on a mutex that is already unlocked.\r
 211  */\r
 212 /* @[declare_platform_threads_mutexunlock] */\r
 213 void IotMutex_Unlock( IotMutex_t * pMutex );\r
 214 /* @[declare_platform_threads_mutexunlock] */\r
 215 \r
 216 /**\r
 217  * @brief Create a new counting semaphore.\r
 218  *\r
 219  * This function creates a new counting semaphore with a given intial and\r
 220  * maximum value. It must be called on an uninitialized #IotSemaphore_t.\r
 221  * This function must not be called on an already-initialized #IotSemaphore_t.\r
 222  *\r
 223  * @param[in] pNewSemaphore Pointer to the memory that will hold the new semaphore.\r
 224  * @param[in] initialValue The semaphore should be initialized with this value.\r
 225  * @param[in] maxValue The maximum value the semaphore will reach.\r
 226  *\r
 227  * @return `true` if semaphore creation succeeds; `false` otherwise.\r
 228  *\r
 229  * @see @ref platform_threads_function_semaphoredestroy\r
 230  *\r
 231  * <b>Example</b>\r
 232  * @code{c}\r
 233  * IotSemaphore_t sem;\r
 234  *\r
 235  * // Create a locked binary semaphore.\r
 236  * if( IotSemaphore_Create( &sem, 0, 1 ) == true )\r
 237  * {\r
 238  *     // Unlock the semaphore.\r
 239  *     IotSemaphore_Post( &sem );\r
 240  *\r
 241  *     // Destroy the semaphore when it's no longer needed.\r
 242  *     IotSemaphore_Destroy( &sem );\r
 243  * }\r
 244  * @endcode\r
 245  */\r
 246 /* @[declare_platform_threads_semaphorecreate] */\r
 247 bool IotSemaphore_Create( IotSemaphore_t * pNewSemaphore,\r
 248                           uint32_t initialValue,\r
 249                           uint32_t maxValue );\r
 250 /* @[declare_platform_threads_semaphorecreate] */\r
 251 \r
 252 /**\r
 253  * @brief Free resources used by a semaphore.\r
 254  *\r
 255  * This function frees resources used by a semaphore. It must be called on an initialized\r
 256  * #IotSemaphore_t. No other semaphore functions should be called on `pSemaphore` after\r
 257  * calling this function (unless the semaphore is re-created).\r
 258  *\r
 259  * @param[in] pSemaphore The semaphore to destroy.\r
 260  *\r
 261  * @warning This function must not be called on a semaphore with waiting threads.\r
 262  * @see @ref platform_threads_function_semaphorecreate\r
 263  */\r
 264 /* @[declare_platform_threads_semaphoredestroy] */\r
 265 void IotSemaphore_Destroy( IotSemaphore_t * pSemaphore );\r
 266 /* @[declare_platform_threads_semaphoredestroy] */\r
 267 \r
 268 /**\r
 269  * @brief Query the current count of the semaphore.\r
 270  *\r
 271  * This function queries a counting semaphore for its current value. A counting\r
 272  * semaphore's value is always 0 or positive.\r
 273  *\r
 274  * @param[in] pSemaphore The semaphore to query.\r
 275  *\r
 276  * @return The current count of the semaphore. This function should not fail.\r
 277  */\r
 278 /* @[declare_platform_threads_semaphoregetcount] */\r
 279 uint32_t IotSemaphore_GetCount( IotSemaphore_t * pSemaphore );\r
 280 /* @[declare_platform_threads_semaphoregetcount] */\r
 281 \r
 282 /**\r
 283  * @brief Wait on (lock) a semaphore. This function should only return when the\r
 284  * semaphore wait succeeds; it is not expected to fail.\r
 285  *\r
 286  * This function blocks and waits until a counting semaphore is positive. It\r
 287  * waits forever (deadlocks) if `pSemaphore` has a count `0` that is never\r
 288  * [incremented](@ref platform_threads_function_semaphorepost).\r
 289  *\r
 290  * @param[in] pSemaphore The semaphore to lock.\r
 291  *\r
 292  * @see @ref platform_threads_function_semaphoretrywait for a nonblocking wait;\r
 293  * @ref platform_threads_function_semaphoretimedwait for a wait with timeout.\r
 294  */\r
 295 /* @[declare_platform_threads_semaphorewait] */\r
 296 void IotSemaphore_Wait( IotSemaphore_t * pSemaphore );\r
 297 /* @[declare_platform_threads_semaphorewait] */\r
 298 \r
 299 /**\r
 300  * @brief Attempt to wait on (lock) a semaphore. Return immediately if the semaphore\r
 301  * is not available.\r
 302  *\r
 303  * If the count of `pSemaphore` is positive, this function immediately decrements\r
 304  * the semaphore and returns. Otherwise, this function returns without decrementing\r
 305  * `pSemaphore`.\r
 306  *\r
 307  * @param[in] pSemaphore The semaphore to lock.\r
 308  *\r
 309  * @return `true` if the semaphore wait succeeded; `false` if the semaphore has\r
 310  * a count of `0`.\r
 311  *\r
 312  * @see @ref platform_threads_function_semaphorewait for a blocking wait;\r
 313  * @ref platform_threads_function_semaphoretimedwait for a wait with timeout.\r
 314  */\r
 315 /* @[declare_platform_threads_semaphoretrywait] */\r
 316 bool IotSemaphore_TryWait( IotSemaphore_t * pSemaphore );\r
 317 /* @[declare_platform_threads_semaphoretrywait] */\r
 318 \r
 319 /**\r
 320  * @brief Attempt to wait on (lock) a semaphore with a timeout.\r
 321  *\r
 322  * This function blocks and waits until a counting semaphore is positive\r
 323  * <i>or</i> its timeout expires (whichever is sooner). It decrements\r
 324  * `pSemaphore` and returns `true` if the semaphore is positive at some\r
 325  * time during the wait. If `pSemaphore` is always `0` during the wait,\r
 326  * this function returns `false`.\r
 327  *\r
 328  * @param[in] pSemaphore The semaphore to lock.\r
 329  * @param[in] timeoutMs Relative timeout of semaphore lock. This function returns\r
 330  * false if the semaphore couldn't be locked within this timeout.\r
 331  *\r
 332  * @return `true` if the semaphore wait succeeded; `false` if it timed out.\r
 333  *\r
 334  * @see @ref platform_threads_function_semaphoretrywait for a nonblocking wait;\r
 335  * @ref platform_threads_function_semaphorewait for a blocking wait.\r
 336  */\r
 337 /* @[declare_platform_threads_semaphoretimedwait] */\r
 338 bool IotSemaphore_TimedWait( IotSemaphore_t * pSemaphore,\r
 339                              uint32_t timeoutMs );\r
 340 /* @[declare_platform_threads_semaphoretimedwait] */\r
 341 \r
 342 /**\r
 343  * @brief Post to (unlock) a semaphore. This function should only return when the\r
 344  * semaphore post succeeds; it is not expected to fail.\r
 345  *\r
 346  * This function increments the count of a semaphore. Any thread may call this\r
 347  * function to increment a semaphore's count.\r
 348  *\r
 349  * @param[in] pSemaphore The semaphore to unlock.\r
 350  */\r
 351 /* @[declare_platform_threads_semaphorepost] */\r
 352 void IotSemaphore_Post( IotSemaphore_t * pSemaphore );\r
 353 /* @[declare_platform_threads_semaphorepost] */\r
 354 \r
 355 #endif /* ifndef IOT_THREADS_H_ */\r