--- /dev/null
+/*\r
+ * IoT Platform V1.1.0\r
+ * Copyright (C) 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.\r
+ *\r
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
+ * this software and associated documentation files (the "Software"), to deal in\r
+ * the Software without restriction, including without limitation the rights to\r
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
+ * the Software, and to permit persons to whom the Software is furnished to do so,\r
+ * subject to the following conditions:\r
+ *\r
+ * The above copyright notice and this permission notice shall be included in all\r
+ * copies or substantial portions of the Software.\r
+ *\r
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
+ */\r
+\r
+/**\r
+ * @file iot_threads.h\r
+ * @brief Threading and synchronization functions used by libraries in this SDK.\r
+ */\r
+\r
+#ifndef IOT_THREADS_H_\r
+#define IOT_THREADS_H_\r
+\r
+/* The config header is always included first. */\r
+#include "iot_config.h"\r
+\r
+/* Standard includes. */\r
+#include <stdbool.h>\r
+#include <stdint.h>\r
+\r
+/* Platform layer types include. */\r
+#include "types/iot_platform_types.h"\r
+\r
+/**\r
+ * @functionspage{platform_threads,platform thread management,Thread Management}\r
+ * - @functionname{platform_threads_function_createdetachedthread}\r
+ * - @functionname{platform_threads_function_mutexcreate}\r
+ * - @functionname{platform_threads_function_mutexdestroy}\r
+ * - @functionname{platform_threads_function_mutexlock}\r
+ * - @functionname{platform_threads_function_mutextrylock}\r
+ * - @functionname{platform_threads_function_mutexunlock}\r
+ * - @functionname{platform_threads_function_semaphorecreate}\r
+ * - @functionname{platform_threads_function_semaphoredestroy}\r
+ * - @functionname{platform_threads_function_semaphoregetcount}\r
+ * - @functionname{platform_threads_function_semaphorewait}\r
+ * - @functionname{platform_threads_function_semaphoretrywait}\r
+ * - @functionname{platform_threads_function_semaphoretimedwait}\r
+ * - @functionname{platform_threads_function_semaphorepost}\r
+ */\r
+\r
+/**\r
+ * @functionpage{Iot_CreateDetachedThread,platform_threads,createdetachedthread}\r
+ * @functionpage{IotMutex_Create,platform_threads,mutexcreate}\r
+ * @functionpage{IotMutex_Destroy,platform_threads,mutexdestroy}\r
+ * @functionpage{IotMutex_Lock,platform_threads,mutexlock}\r
+ * @functionpage{IotMutex_TryLock,platform_threads,mutextrylock}\r
+ * @functionpage{IotMutex_Unlock,platform_threads,mutexunlock}\r
+ * @functionpage{IotSemaphore_Create,platform_threads,semaphorecreate}\r
+ * @functionpage{IotSemaphore_Destroy,platform_threads,semaphoredestroy}\r
+ * @functionpage{IotSemaphore_GetCount,platform_threads,semaphoregetcount}\r
+ * @functionpage{IotSemaphore_Wait,platform_threads,semaphorewait}\r
+ * @functionpage{IotSemaphore_TryWait,platform_threads,semaphoretrywait}\r
+ * @functionpage{IotSemaphore_TimedWait,platform_threads,semaphoretimedwait}\r
+ * @functionpage{IotSemaphore_Post,platform_threads,semaphorepost}\r
+ */\r
+\r
+/**\r
+ * @brief Create a new detached thread, i.e. a thread that cleans up after itself.\r
+ *\r
+ * This function creates a new thread. Threads created by this function exit\r
+ * upon returning from the thread routine. Any resources taken must be freed\r
+ * by the exiting thread.\r
+ *\r
+ * @param[in] threadRoutine The function this thread should run.\r
+ * @param[in] pArgument The argument passed to `threadRoutine`.\r
+ * @param[in] priority Represents the priority of the new thread, as defined by\r
+ * the system. The value #IOT_THREAD_DEFAULT_PRIORITY (i.e. `0`) must be used to\r
+ * represent the system default for thread priority.\r
+ * @param[in] stackSize Represents the stack size of the new thread, as defined\r
+ * by the system. The value #IOT_THREAD_DEFAULT_STACK_SIZE (i.e. `0`) must be used\r
+ * to represent the system default for stack size.\r
+ *\r
+ * @return `true` if the new thread was successfully created; `false` otherwise.\r
+ *\r
+ * @code{c}\r
+ * // Thread routine.\r
+ * void threadRoutine( void * pArgument );\r
+ *\r
+ * // Run threadRoutine in a detached thread, using default priority and stack size.\r
+ * if( Iot_CreateDetachedThread( threadRoutine,\r
+ * NULL,\r
+ * IOT_THREAD_DEFAULT_PRIORITY,\r
+ * IOT_THREAD_DEFAULT_STACK_SIZE ) == true )\r
+ * {\r
+ * // Success\r
+ * }\r
+ * else\r
+ * {\r
+ * // Failure, no thread was created.\r
+ * }\r
+ * @endcode\r
+ */\r
+/* @[declare_platform_threads_createdetachedthread] */\r
+bool Iot_CreateDetachedThread( IotThreadRoutine_t threadRoutine,\r
+ void * pArgument,\r
+ int32_t priority,\r
+ size_t stackSize );\r
+/* @[declare_platform_threads_createdetachedthread] */\r
+\r
+/**\r
+ * @brief Create a new mutex.\r
+ *\r
+ * This function creates a new, unlocked mutex. It must be called on an uninitialized\r
+ * #IotMutex_t. This function must not be called on an already-initialized #IotMutex_t.\r
+ *\r
+ * @param[in] pNewMutex Pointer to the memory that will hold the new mutex.\r
+ * @param[in] recursive Set to `true` to create a recursive mutex, i.e. a mutex that\r
+ * may be locked multiple times by the same thread. If the system does not support\r
+ * recursive mutexes, this function should do nothing and return `false`.\r
+ *\r
+ * @return `true` if mutex creation succeeds; `false` otherwise.\r
+ *\r
+ * @see @ref platform_threads_function_mutexdestroy\r
+ *\r
+ * <b>Example</b>\r
+ * @code{c}\r
+ * IotMutex_t mutex;\r
+ *\r
+ * // Create non-recursive mutex.\r
+ * if( IotMutex_Create( &mutex, false ) == true )\r
+ * {\r
+ * // Lock and unlock the mutex...\r
+ *\r
+ * // Destroy the mutex when it's no longer needed.\r
+ * IotMutex_Destroy( &mutex );\r
+ * }\r
+ * @endcode\r
+ */\r
+/* @[declare_platform_threads_mutexcreate] */\r
+bool IotMutex_Create( IotMutex_t * pNewMutex, bool recursive );\r
+/* @[declare_platform_threads_mutexcreate] */\r
+\r
+/**\r
+ * @brief Free resources used by a mutex.\r
+ *\r
+ * This function frees resources used by a mutex. It must be called on an initialized\r
+ * #IotMutex_t. No other mutex functions should be called on `pMutex` after calling\r
+ * this function (unless the mutex is re-created).\r
+ *\r
+ * @param[in] pMutex The mutex to destroy.\r
+ *\r
+ * @warning This function must not be called on a locked mutex.\r
+ * @see @ref platform_threads_function_mutexcreate\r
+ */\r
+/* @[declare_platform_threads_mutexdestroy] */\r
+void IotMutex_Destroy( IotMutex_t * pMutex );\r
+/* @[declare_platform_threads_mutexdestroy] */\r
+\r
+/**\r
+ * @brief Lock a mutex. This function should only return when the mutex is locked;\r
+ * it is not expected to fail.\r
+ *\r
+ * This function blocks and waits until a mutex is available. It waits forever\r
+ * (deadlocks) if `pMutex` is already locked and never unlocked.\r
+ *\r
+ * @param[in] pMutex The mutex to lock.\r
+ *\r
+ * @see @ref platform_threads_function_mutextrylock for a nonblocking lock.\r
+ */\r
+/* @[declare_platform_threads_mutexlock] */\r
+void IotMutex_Lock( IotMutex_t * pMutex );\r
+/* @[declare_platform_threads_mutexlock] */\r
+\r
+/**\r
+ * @brief Attempt to lock a mutex. Return immediately if the mutex is not available.\r
+ *\r
+ * If `pMutex` is available, this function immediately locks it and returns.\r
+ * Otherwise, this function returns without locking `pMutex`.\r
+ *\r
+ * @param[in] pMutex The mutex to lock.\r
+ *\r
+ * @return `true` if the mutex was successfully locked; `false` if the mutex was\r
+ * not available.\r
+ *\r
+ * @see @ref platform_threads_function_mutexlock for a blocking lock.\r
+ */\r
+/* @[declare_platform_threads_mutextrylock] */\r
+bool IotMutex_TryLock( IotMutex_t * pMutex );\r
+/* @[declare_platform_threads_mutextrylock] */\r
+\r
+/**\r
+ * @brief Unlock a mutex. This function should only return when the mutex is unlocked;\r
+ * it is not expected to fail.\r
+ *\r
+ * Unlocks a locked mutex. `pMutex` must have been locked by the thread calling\r
+ * this function.\r
+ *\r
+ * @param[in] pMutex The mutex to unlock.\r
+ *\r
+ * @note This function should not be called on a mutex that is already unlocked.\r
+ */\r
+/* @[declare_platform_threads_mutexunlock] */\r
+void IotMutex_Unlock( IotMutex_t * pMutex );\r
+/* @[declare_platform_threads_mutexunlock] */\r
+\r
+/**\r
+ * @brief Create a new counting semaphore.\r
+ *\r
+ * This function creates a new counting semaphore with a given initial and\r
+ * maximum value. It must be called on an uninitialized #IotSemaphore_t.\r
+ * This function must not be called on an already-initialized #IotSemaphore_t.\r
+ *\r
+ * @param[in] pNewSemaphore Pointer to the memory that will hold the new semaphore.\r
+ * @param[in] initialValue The semaphore should be initialized with this value.\r
+ * @param[in] maxValue The maximum value the semaphore will reach.\r
+ *\r
+ * @return `true` if semaphore creation succeeds; `false` otherwise.\r
+ *\r
+ * @see @ref platform_threads_function_semaphoredestroy\r
+ *\r
+ * <b>Example</b>\r
+ * @code{c}\r
+ * IotSemaphore_t sem;\r
+ *\r
+ * // Create a locked binary semaphore.\r
+ * if( IotSemaphore_Create( &sem, 0, 1 ) == true )\r
+ * {\r
+ * // Unlock the semaphore.\r
+ * IotSemaphore_Post( &sem );\r
+ *\r
+ * // Destroy the semaphore when it's no longer needed.\r
+ * IotSemaphore_Destroy( &sem );\r
+ * }\r
+ * @endcode\r
+ */\r
+/* @[declare_platform_threads_semaphorecreate] */\r
+bool IotSemaphore_Create( IotSemaphore_t * pNewSemaphore,\r
+ uint32_t initialValue,\r
+ uint32_t maxValue );\r
+/* @[declare_platform_threads_semaphorecreate] */\r
+\r
+/**\r
+ * @brief Free resources used by a semaphore.\r
+ *\r
+ * This function frees resources used by a semaphore. It must be called on an initialized\r
+ * #IotSemaphore_t. No other semaphore functions should be called on `pSemaphore` after\r
+ * calling this function (unless the semaphore is re-created).\r
+ *\r
+ * @param[in] pSemaphore The semaphore to destroy.\r
+ *\r
+ * @warning This function must not be called on a semaphore with waiting threads.\r
+ * @see @ref platform_threads_function_semaphorecreate\r
+ */\r
+/* @[declare_platform_threads_semaphoredestroy] */\r
+void IotSemaphore_Destroy( IotSemaphore_t * pSemaphore );\r
+/* @[declare_platform_threads_semaphoredestroy] */\r
+\r
+/**\r
+ * @brief Query the current count of the semaphore.\r
+ *\r
+ * This function queries a counting semaphore for its current value. A counting\r
+ * semaphore's value is always 0 or positive.\r
+ *\r
+ * @param[in] pSemaphore The semaphore to query.\r
+ *\r
+ * @return The current count of the semaphore. This function should not fail.\r
+ */\r
+/* @[declare_platform_threads_semaphoregetcount] */\r
+uint32_t IotSemaphore_GetCount( IotSemaphore_t * pSemaphore );\r
+/* @[declare_platform_threads_semaphoregetcount] */\r
+\r
+/**\r
+ * @brief Wait on (lock) a semaphore. This function should only return when the\r
+ * semaphore wait succeeds; it is not expected to fail.\r
+ *\r
+ * This function blocks and waits until a counting semaphore is positive. It\r
+ * waits forever (deadlocks) if `pSemaphore` has a count `0` that is never\r
+ * [incremented](@ref platform_threads_function_semaphorepost).\r
+ *\r
+ * @param[in] pSemaphore The semaphore to lock.\r
+ *\r
+ * @see @ref platform_threads_function_semaphoretrywait for a nonblocking wait;\r
+ * @ref platform_threads_function_semaphoretimedwait for a wait with timeout.\r
+ */\r
+/* @[declare_platform_threads_semaphorewait] */\r
+void IotSemaphore_Wait( IotSemaphore_t * pSemaphore );\r
+/* @[declare_platform_threads_semaphorewait] */\r
+\r
+/**\r
+ * @brief Attempt to wait on (lock) a semaphore. Return immediately if the semaphore\r
+ * is not available.\r
+ *\r
+ * If the count of `pSemaphore` is positive, this function immediately decrements\r
+ * the semaphore and returns. Otherwise, this function returns without decrementing\r
+ * `pSemaphore`.\r
+ *\r
+ * @param[in] pSemaphore The semaphore to lock.\r
+ *\r
+ * @return `true` if the semaphore wait succeeded; `false` if the semaphore has\r
+ * a count of `0`.\r
+ *\r
+ * @see @ref platform_threads_function_semaphorewait for a blocking wait;\r
+ * @ref platform_threads_function_semaphoretimedwait for a wait with timeout.\r
+ */\r
+/* @[declare_platform_threads_semaphoretrywait] */\r
+bool IotSemaphore_TryWait( IotSemaphore_t * pSemaphore );\r
+/* @[declare_platform_threads_semaphoretrywait] */\r
+\r
+/**\r
+ * @brief Attempt to wait on (lock) a semaphore with a timeout.\r
+ *\r
+ * This function blocks and waits until a counting semaphore is positive\r
+ * <i>or</i> its timeout expires (whichever is sooner). It decrements\r
+ * `pSemaphore` and returns `true` if the semaphore is positive at some\r
+ * time during the wait. If `pSemaphore` is always `0` during the wait,\r
+ * this function returns `false`.\r
+ *\r
+ * @param[in] pSemaphore The semaphore to lock.\r
+ * @param[in] timeoutMs Relative timeout of semaphore lock. This function returns\r
+ * false if the semaphore couldn't be locked within this timeout.\r
+ *\r
+ * @return `true` if the semaphore wait succeeded; `false` if it timed out.\r
+ *\r
+ * @see @ref platform_threads_function_semaphoretrywait for a nonblocking wait;\r
+ * @ref platform_threads_function_semaphorewait for a blocking wait.\r
+ */\r
+/* @[declare_platform_threads_semaphoretimedwait] */\r
+bool IotSemaphore_TimedWait( IotSemaphore_t * pSemaphore,\r
+ uint32_t timeoutMs );\r
+/* @[declare_platform_threads_semaphoretimedwait] */\r
+\r
+/**\r
+ * @brief Post to (unlock) a semaphore. This function should only return when the\r
+ * semaphore post succeeds; it is not expected to fail.\r
+ *\r
+ * This function increments the count of a semaphore. Any thread may call this\r
+ * function to increment a semaphore's count.\r
+ *\r
+ * @param[in] pSemaphore The semaphore to unlock.\r
+ */\r
+/* @[declare_platform_threads_semaphorepost] */\r
+void IotSemaphore_Post( IotSemaphore_t * pSemaphore );\r
+/* @[declare_platform_threads_semaphorepost] */\r
+\r
+#endif /* ifndef IOT_THREADS_H_ */\r
projects / freertos / blobdiff