1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup DriverUtils 11 * @{ 12 * 13 * @brief Defines common macros and interfaces of the driver module. 14 * 15 * This module provides interfaces such as log printing, doubly linked list operations, and work queues. 16 * 17 * @since 1.0 18 * @version 1.0 19 */ 20 21 /** 22 * @file hdf_workqueue.h 23 * 24 * @brief Declares work queue structures and interfaces. 25 * 26 * This file provides interfaces such as initializing a work queue, a work item, and a delayed work item, 27 * adding a work or delayed work item to a work queue, and destroying a work queue, a work item, 28 * and a delayed work item. You need to define a work queue, a work item, and a delayed work item, 29 * and then call the initialization function to initialize them. The work item, delayed work item, 30 * and work queue must be destroyed when they are no longer used. 31 * 32 * @since 1.0 33 * @version 1.0 34 */ 35 #ifndef HDF_WORKQUEUE_H 36 #define HDF_WORKQUEUE_H 37 38 #include "hdf_base.h" 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif /* __cplusplus */ 43 44 /** 45 * @brief Describes a work execution function type. 46 * 47 * The thread of the work queue executes this function after the work item is added to the work queue. 48 */ 49 typedef void (*HdfWorkFunc)(void *); 50 51 /** 52 * @brief Enumerates statuses of a work item or a delayed work item. 53 */ 54 enum { 55 HDF_WORK_BUSY_PENDING = 1 << 0, /**< The work item or delayed work item is pending. */ 56 HDF_WORK_BUSY_RUNNING = 1 << 1, /**< The work item or delayed work item is running. */ 57 }; 58 /** 59 * @brief Describes a work item and a delayed work item. 60 * This structure defines the work and delayed work items, and then calls the initialization 61 * function {@link HdfWorkInit} or {@link HdfDelayedWorkInit} to perform initialization. 62 * The <b>HdfAddWork()</b> function is to add a work item to a work queue immediately, 63 * and the <b>HdfAddDelayedWork()</b> function is to add a work item to a work queue after the configured delayed time. 64 */ 65 typedef struct { 66 void *realWork; /**< Pointer to a work item and a delayed work item */ 67 } HdfWork; 68 69 /** 70 * @brief Describes a work queue. 71 */ 72 typedef struct { 73 void *realWorkQueue; /**< Pointer to a work queue */ 74 } HdfWorkQueue; 75 76 /** 77 * @brief Initializes a work queue. 78 * 79 * When a work queue is initialized, a thread is created. The thread cyclically executes the work items 80 * in the work queue, that is, executes their functions. 81 * 82 * @param queue Indicates the pointer to the work queue {@link OsalWorkQueue}. 83 * @param name Indicates the pointer to the work queue name. 84 * 85 * @return Returns a value listed below: \n 86 * HDF_STATUS | Description 87 * ----------------------| ----------------------- 88 * HDF_SUCCESS | The operation is successful. 89 * HDF_ERR_INVALID_PARAM | Invalid parameter. 90 * HDF_ERR_MALLOC_FAIL | Memory allocation fails. 91 * 92 * @since 1.0 93 * @version 1.0 94 */ 95 int32_t HdfWorkQueueInit(HdfWorkQueue *queue, char *name); 96 97 /** 98 * @brief Initializes a work item. 99 * 100 * This function uses <b>func</b> and <b>arg</b> to initialize a work item. 101 * After the work item is added to a work queue, the thread of the work queue executes this function, 102 * and <b>arg</b> is passed to <b>func</b>. 103 * 104 * @param work Indicates the pointer to the work item {@link HdfWork}. 105 * @param func Indicates the work execution function. 106 * @param arg Indicates the pointer to the argument of the work execution function. 107 * 108 * @return Returns a value listed below: \n 109 * HDF_STATUS | Description 110 * ----------------------| ----------------------- 111 * HDF_SUCCESS | The operation is successful. 112 * HDF_ERR_INVALID_PARAM | Invalid parameter. 113 * HDF_ERR_MALLOC_FAIL | Memory allocation fails. 114 * 115 * @since 1.0 116 * @version 1.0 117 */ 118 int32_t HdfWorkInit(HdfWork *work, HdfWorkFunc func, void *arg); 119 120 /** 121 * @brief Initializes a delayed work item. 122 * 123 * This function uses <b>func</b> and <b>arg</b> to initialize a work item. 124 * The work item is added to a work queue after the configured delayed time. 125 * The thread of the work queue executes this function, and <b>arg</b> is passed to <b>func</b>. 126 * 127 * @param work Indicates the pointer to the delayed work item {@link HdfWork}. 128 * @param func Indicates the work execution function. 129 * @param arg Indicates the pointer to the argument of the work execution function. 130 * 131 * @return Returns a value listed below: \n 132 * HDF_STATUS | Description 133 * ----------------------| ----------------------- 134 * HDF_SUCCESS | The operation is successful. 135 * HDF_ERR_INVALID_PARAM | Invalid parameter. 136 * HDF_ERR_MALLOC_FAIL | Memory allocation fails. 137 * 138 * @since 1.0 139 * @version 1.0 140 */ 141 int32_t HdfDelayedWorkInit(HdfWork *work, HdfWorkFunc func, void *arg); 142 143 /** 144 * @brief Destroys a work item. 145 * 146 * @param work Indicates the pointer to the work item {@link HdfWork}. 147 * @since 1.0 148 * @version 1.0 149 */ 150 void HdfWorkDestroy(HdfWork *work); 151 152 /** 153 * @brief Destroys a work queue. 154 * 155 * @param queue Indicates the pointer to the work queue {@link HdfWorkQueue}. 156 * @since 1.0 157 * @version 1.0 158 */ 159 void HdfWorkQueueDestroy(HdfWorkQueue *queue); 160 161 /** 162 * @brief Destroys a delayed work item. 163 * 164 * @param work Indicates the pointer to the delayed work item {@link HdfWork}. 165 * @since 1.0 166 * @version 1.0 167 */ 168 void HdfDelayedWorkDestroy(HdfWork *work); 169 170 /** 171 * @brief Adds a work item to a work queue. 172 * 173 * After a work item is added to a work queue, the thread of the work queue executes the function of the work item. 174 * 175 * @param queue Indicates the pointer to the work queue {@link HdfWorkQueue}. 176 * @param work Indicates the pointer to the work item {@link HdfWork}. 177 * @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise. 178 * @since 1.0 179 * @version 1.0 180 */ 181 bool HdfAddWork(HdfWorkQueue *queue, HdfWork *work); 182 183 /** 184 * @brief Adds a delayed work item to a work queue. 185 * 186 * A delayed work item is added to a work queue after the configured delayed time (ms), 187 * and the thread of the work queue executes the work function. 188 * 189 * @param queue Indicates the pointer to the work queue {@link HdfWorkQueue}. 190 * @param work Indicates the pointer to the delayed work item {@link HdfWork}. 191 * @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise. 192 * @since 1.0 193 * @version 1.0 194 */ 195 bool HdfAddDelayedWork(HdfWorkQueue *queue, HdfWork *work, uint32_t ms); 196 197 /** 198 * @brief Obtains the status of a work item or delayed work item. 199 * 200 * @param work Indicates the pointer to the work item or delayed work item {@link HdfWork}. 201 * @return Returns <b>HDF_WORK_BUSY_PENDING</b> if the work item is pending; 202 * returns <b>HDF_WORK_BUSY_RUNNING</b> if the work item is running. 203 * @since 1.0 204 * @version 1.0 205 */ 206 unsigned int HdfWorkBusy(HdfWork *work); 207 208 /** 209 * @brief Cancels a work item. This function waits until the work item is complete. 210 * 211 * @param work Indicates the pointer to the work item {@link HdfWork}. 212 * @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise. 213 * @since 1.0 214 * @version 1.0 215 */ 216 bool HdfCancelWorkSync(HdfWork *work); 217 218 /** 219 * @brief Cancels a delayed work item. 220 * 221 * @param work Indicates the pointer to the delayed work item {@link HdfWork}. 222 * @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise. 223 * @since 1.0 224 * @version 1.0 225 */ 226 bool HdfCancelDelayedWorkSync(HdfWork *work); 227 228 #ifdef __cplusplus 229 } 230 #endif /* __cplusplus */ 231 232 #endif /* HDF_WORKQUEUE_H */ 233 /** @} */ 234