git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/FreeRTOS-IoT-Libraries/c_sdk/platform/iot_threads.h

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