--- /dev/null
+/*\r
+ * IoT Common V1.0.0\r
+ * Copyright (C) 2019 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_taskpool_types.h\r
+ * @brief Types of the task pool.\r
+ */\r
+\r
+#ifndef IOT_TASKPOOL_TYPES_H_\r
+#define IOT_TASKPOOL_TYPES_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 types includes. */\r
+#include "types/iot_platform_types.h"\r
+\r
+/* Linear containers (lists and queues) include. */\r
+#include "iot_linear_containers.h"\r
+\r
+/*-------------------------- Task pool enumerated types --------------------------*/\r
+\r
+/**\r
+ * @ingroup taskpool_datatypes_enums\r
+ * @brief Return codes of [task pool functions](@ref taskpool_functions).\r
+ */\r
+typedef enum IotTaskPoolError\r
+{\r
+ /**\r
+ * @brief Task pool operation completed successfully.\r
+ */\r
+ IOT_TASKPOOL_SUCCESS = 0,\r
+\r
+ /**\r
+ * @brief Task pool operation failed because at least one parameter is invalid.\r
+ */\r
+ IOT_TASKPOOL_BAD_PARAMETER,\r
+\r
+ /**\r
+ * @brief Task pool operation failed because it is illegal.\r
+ */\r
+ IOT_TASKPOOL_ILLEGAL_OPERATION,\r
+\r
+ /**\r
+ * @brief Task pool operation failed because allocating memory failed.\r
+ */\r
+ IOT_TASKPOOL_NO_MEMORY,\r
+\r
+ /**\r
+ * @brief Task pool operation failed because of an invalid parameter.\r
+ */\r
+ IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS,\r
+\r
+ /**\r
+ * @brief Task pool cancellation failed.\r
+ */\r
+ IOT_TASKPOOL_CANCEL_FAILED,\r
+\r
+ /**\r
+ * @brief Task pool operation general failure.\r
+ */\r
+ IOT_TASKPOOL_GENERAL_FAILURE,\r
+} IotTaskPoolError_t;\r
+\r
+/**\r
+ * @enums{taskpool,Task pool library}\r
+ */\r
+\r
+/**\r
+ * @ingroup taskpool_datatypes_enums\r
+ * @brief Status codes of [task pool Job](@ref IotTaskPoolJob_t).\r
+ *\r
+ */\r
+typedef enum IotTaskPoolJobStatus\r
+{\r
+ /**\r
+ * @brief Job is ready to be scheduled.\r
+ *\r
+ */\r
+ IOT_TASKPOOL_STATUS_READY = 0,\r
+\r
+ /**\r
+ * @brief Job has been queued for execution.\r
+ *\r
+ */\r
+ IOT_TASKPOOL_STATUS_SCHEDULED,\r
+\r
+ /**\r
+ * @brief Job has been scheduled for deferred execution.\r
+ *\r
+ */\r
+ IOT_TASKPOOL_STATUS_DEFERRED,\r
+\r
+ /**\r
+ * @brief Job is executing.\r
+ *\r
+ */\r
+ IOT_TASKPOOL_STATUS_COMPLETED,\r
+\r
+ /**\r
+ * @brief Job has been canceled before executing.\r
+ *\r
+ */\r
+ IOT_TASKPOOL_STATUS_CANCELED,\r
+\r
+ /**\r
+ * @brief Job status is undefined.\r
+ *\r
+ */\r
+ IOT_TASKPOOL_STATUS_UNDEFINED,\r
+} IotTaskPoolJobStatus_t;\r
+\r
+/*------------------------- Task pool types and handles --------------------------*/\r
+\r
+/**\r
+ * @ingroup taskpool_datatypes_handles\r
+ * @brief Opaque handle of a Task Pool instance.\r
+ *\r
+ * This type identifies a Task Pool instance, which is valid after a successful call\r
+ * to @ref taskpool_function_createsystemtaskpool. \r
+ *\r
+ * @initializer{IotTaskPool_t,IOT_TASKPOOL_INITIALIZER}\r
+ */\r
+typedef struct _taskPool * IotTaskPool_t;\r
+\r
+/**\r
+ * @ingroup taskpool_datatypes_handles\r
+ * @brief A storage placeholder for TaskPool Jobs.\r
+ *\r
+ * This type provides a means to statically allocate an IoT TaskPool Job while\r
+ * hiding internal details.\r
+ */\r
+typedef struct IotTaskPoolJobStorage IotTaskPoolJobStorage_t;\r
+\r
+/**\r
+ * @ingroup taskpool_datatypes_structs\r
+ * @brief A storage placeholder for private data in the IotTaskPoolJobStorage struct.\r
+ *\r
+ * @warning This is a system-level data type that should not be modified or used directly in any application.\r
+ * @warning This is a system-level data type that can and will change across different versions of the platform, with no regards for backward compatibility.\r
+ */\r
+struct PrivateMember\r
+{\r
+ IotLink_t dummy1; /**< @brief Placeholder. */\r
+ TickType_t dummy2; /**< @brief Placeholder. */\r
+};\r
+\r
+/**\r
+ * @ingroup taskpool_datatypes_structs\r
+ * @brief The job storage data structure provides the storage for a statically allocated Task Pool Job instance.\r
+ *\r
+ * @warning This is a system-level data type that should not be modified or used directly in any application.\r
+ * @warning This is a system-level data type that can and will change across different versions of the platform, with no regards for backward compatibility.\r
+ *\r
+ */\r
+struct IotTaskPoolJobStorage\r
+{\r
+ IotLink_t link; /**< @brief Placeholder. */\r
+ void * dummy2; /**< @brief Placeholder. */\r
+ void * dummy3; /**< @brief Placeholder. */\r
+ IotTaskPoolJobStatus_t status; /**< @brief Placeholder. */\r
+ struct PrivateMember dummy6; /**< @brief Placeholder. */\r
+};\r
+\r
+/**\r
+ * @ingroup taskpool_datatypes_handles\r
+ * @brief Opaque handle of a Task Pool Job.\r
+ * \r
+ * This type identifies a Task Pool Job instance, which is valid after a successful call\r
+ * to @ref taskpool_function_createjob.\r
+ *\r
+ * @initializer{IotTaskPoolJob_t,IOT_TASKPOOL_JOB_INITIALIZER}\r
+ *\r
+ */\r
+typedef struct _taskPoolJob * IotTaskPoolJob_t;\r
+\r
+/*------------------------- Task pool parameter structs --------------------------*/\r
+\r
+/**\r
+ * @ingroup taskpool_datatypes_functionpointers\r
+ * @brief Callback type for a user callback.\r
+ *\r
+ * This type identifies the user callback signature to execute a task pool job. This callback will be invoked\r
+ * by the task pool threads with the `pUserContext` parameter, as specified by the user when\r
+ * calling @ref IotTaskPool_Schedule.\r
+ *\r
+ */\r
+typedef void ( * IotTaskPoolRoutine_t )( IotTaskPool_t pTaskPool,\r
+ IotTaskPoolJob_t pJob,\r
+ void * pUserContext );\r
+\r
+/**\r
+ * @ingroup taskpool_datatypes_paramstructs\r
+ * @brief Initialization information to create one task pool instance.\r
+ *\r
+ * @paramfor @ref taskpool_function_createsystemtaskpool\r
+ *\r
+ * @initializer{IotTaskPoolInfo_t,IOT_TASKPOOL_INFO_INITIALIZER}\r
+ */\r
+typedef struct IotTaskPoolInfo\r
+{\r
+ /**\r
+ * @brief Specifies the operating parameters for a task pool.\r
+ *\r
+ * @attention #IotTaskPoolInfo_t.minThreads <b>MUST</b> be at least 1.\r
+ */\r
+\r
+ uint32_t minThreads; /**< @brief Minimum number of threads in a task pool. These tasks will be statically allocated. */\r
+ uint32_t maxThreads; /**< @brief Maximum number of threads in a task pool. This is fixed for the lifetime of the taskpool. */\r
+ uint32_t stackSize; /**< @brief Stack size for every task pool thread. The stack size for each thread is fixed after the task pool is created and cannot be changed. */\r
+ int32_t priority; /**< @brief priority for every task pool thread. The priority for each thread is fixed after the task pool is created and cannot be changed. */\r
+} IotTaskPoolInfo_t;\r
+\r
+/*------------------------- TASKPOOL defined constants --------------------------*/\r
+\r
+/**\r
+ * @constantspage{taskpool,task pool library}\r
+ *\r
+ * @section taskpool_constants_initializers Task pool Initializers\r
+ * @brief Provides default values for initializing the data types of the task pool library.\r
+ *\r
+ * @snippet this define_taskpool_initializers\r
+ *\r
+ * All user-facing data types of the task pool library can be initialized using\r
+ * one of the following.\r
+ *\r
+ * @warning Failure to initialize a task pool data type with the appropriate initializer\r
+ * may result in a runtime error!\r
+ * @note The initializers may change at any time in future versions, but their\r
+ * names will remain the same.\r
+ *\r
+ * <b>Example</b>\r
+ * @code{c}\r
+ *\r
+ * IotTaskPool_t * pTaskPool;\r
+ *\r
+ * const IotTaskPoolInfo_t tpInfo = IOT_TASKPOOL_INFO_INITIALIZER_LARGE;\r
+ *\r
+ * IotTaskPoolError_t error = IotTaskPool_Create( &tpInfo, &pTaskPool );\r
+ *\r
+ * // Use the task pool\r
+ * // ...\r
+ *\r
+ * @endcode\r
+ *\r
+ */\r
+/* @[define_taskpool_initializers] */\r
+/** @brief Initializer for a small #IotTaskPoolInfo_t. */\r
+#define IOT_TASKPOOL_INFO_INITIALIZER_SMALL { .minThreads = 1, .maxThreads = 1, .stackSize = IOT_THREAD_DEFAULT_STACK_SIZE, .priority = IOT_THREAD_DEFAULT_PRIORITY }\r
+/** @brief Initializer for a medium #IotTaskPoolInfo_t. */\r
+#define IOT_TASKPOOL_INFO_INITIALIZER_MEDIUM { .minThreads = 1, .maxThreads = 2, .stackSize = IOT_THREAD_DEFAULT_STACK_SIZE, .priority = IOT_THREAD_DEFAULT_PRIORITY }\r
+/** @brief Initializer for a large #IotTaskPoolInfo_t. */\r
+#define IOT_TASKPOOL_INFO_INITIALIZER_LARGE { .minThreads = 2, .maxThreads = 3, .stackSize = IOT_THREAD_DEFAULT_STACK_SIZE, .priority = IOT_THREAD_DEFAULT_PRIORITY }\r
+/** @brief Initializer for a very large #IotTaskPoolInfo_t. */\r
+#define IOT_TASKPOOL_INFO_INITIALIZER_XLARGE { .minThreads = 2, .maxThreads = 4, .stackSize = IOT_THREAD_DEFAULT_STACK_SIZE, .priority = IOT_THREAD_DEFAULT_PRIORITY }\r
+/** @brief Initializer for a typical #IotTaskPoolInfo_t. */\r
+#define IOT_TASKPOOL_INFO_INITIALIZER IOT_TASKPOOL_INFO_INITIALIZER_MEDIUM\r
+/** @brief Initializer for a #IotTaskPool_t. */\r
+#define IOT_TASKPOOL_INITIALIZER NULL\r
+/** @brief Initializer for a #IotTaskPoolJobStorage_t. */\r
+#define IOT_TASKPOOL_JOB_STORAGE_INITIALIZER { { NULL, NULL }, NULL, NULL, 0, IOT_TASKPOOL_STATUS_UNDEFINED }\r
+/** @brief Initializer for a #IotTaskPoolJob_t. */\r
+#define IOT_TASKPOOL_JOB_INITIALIZER NULL\r
+/* @[define_taskpool_initializers] */\r
+\r
+/**\r
+ * @brief Flag for scheduling a job to execute immediately, even if the maximum number of threads in the\r
+ * task pool was reached already.\r
+ *\r
+ * @warning This flag may cause the task pool to create a worker to serve the job immediately, and\r
+ * therefore using this flag may incur in additional memory usage and potentially fail scheduling the job.\r
+ */\r
+#define IOT_TASKPOOL_JOB_HIGH_PRIORITY ( ( uint32_t ) 0x00000001 )\r
+\r
+/**\r
+ * @brief Allows the use of the handle to the system task pool.\r
+ *\r
+ * @warning The system task pool handle is not valid unless @ref IotTaskPool_CreateSystemTaskPool is\r
+ * called before the handle is used.\r
+ */\r
+#define IOT_SYSTEM_TASKPOOL ( NULL )\r
+\r
+#endif /* ifndef IOT_TASKPOOL_TYPES_H_ */\r
projects / freertos / blobdiff