1 /* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup QoS 18 * @{ 19 * 20 * @brief QoS provides APIs. 21 * 22 * @since 12 23 */ 24 25 /** 26 * @file qos.h 27 * 28 * @brief Declares the QoS interfaces in C. 29 * 30 * Quality-of-service (QoS) refers to the priority scheduling attribute of tasks 31 * in OpenHarmony. Developers can use QoS to categorize tasks to be executed to 32 * indicate the degree of their relevance to user interactions, the system can 33 * schedule the time and running order of tasks according to the QoS set by the tasks. 34 * 35 * @library libqos.so 36 * @kit KernelEnhanceKit 37 * @syscap SystemCapability.Resourceschedule.QoS.Core 38 * @since 12 39 */ 40 41 #ifndef QOS_H 42 #define QOS_H 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * @brief Describes the level of QoS. 50 * 51 * @since 12 52 */ 53 typedef enum QoS_Level { 54 /** 55 * @brief Means the QoS level is background. 56 */ 57 QOS_BACKGROUND = 0, 58 59 /** 60 * @brief Means the QoS level is utility. 61 */ 62 QOS_UTILITY, 63 64 /** 65 * @brief Means the QoS level is default. 66 */ 67 QOS_DEFAULT, 68 69 /** 70 * @brief Means the QoS level is user-initiated. 71 */ 72 QOS_USER_INITIATED, 73 74 /** 75 * @brief Means the QoS level is user-request. 76 */ 77 QOS_DEADLINE_REQUEST, 78 79 /** 80 * @brief Means the QoS level is user-interactive. 81 */ 82 QOS_USER_INTERACTIVE, 83 } QoS_Level; 84 85 /** 86 * @brief Set the QoS level of the current thread. 87 * 88 * @param level Indicates the level to set. Specific level can be referenced {@link QoS_Level}. 89 * @return Returns 0 if the operation is successful; returns -1 if level is out of range or 90 * internal error failed. 91 * @see QoS_Level 92 * @since 12 93 */ 94 int OH_QoS_SetThreadQoS(QoS_Level level); 95 96 /** 97 * @brief Cancel the QoS level of the current thread. 98 * 99 * @return Returns 0 if the operation is successful; returns -1 if not set QoS for current thread 100 * or internal error failed. 101 * @see QoS_Level 102 * @since 12 103 */ 104 int OH_QoS_ResetThreadQoS(); 105 106 /** 107 * @brief Obtains the QoS level of the current thread. 108 * 109 * @param level This parameter is the output parameter, 110 * and the QoS level of the thread as a {@link QoS_Level} is written to this variable. 111 * @return Returns 0 if the operation is successful; returns -1 if level is null, not 112 * set QoS for current thread or internal error failed. 113 * @see QoS_Level 114 * @since 12 115 */ 116 int OH_QoS_GetThreadQoS(QoS_Level *level); 117 118 /** 119 * @brief Session id 120 * 121 * @since 20 122 */ 123 typedef unsigned int OH_QoS_GewuSession; 124 #define OH_QOS_GEWU_INVALID_SESSION_ID (static_cast<OH_QoS_GewuSession>(0xffffffffU)) 125 /** 126 * @brief Request id 127 * 128 * @since 20 129 */ 130 typedef unsigned int OH_QoS_GewuRequest; 131 #define OH_QOS_GEWU_INVALID_REQUEST_ID (static_cast<OH_QoS_GewuRequest>(0xffffffffU)) 132 133 134 /** 135 * @brief Gewu error codes. 136 * 137 * @since 20 138 */ 139 typedef enum { 140 OH_QOS_GEWU_OK = 0, 141 OH_QOS_GEWU_NOPERM = 201, 142 OH_QOS_GEWU_NOMEM = 203, 143 OH_QOS_GEWU_INVAL = 401, 144 OH_QOS_GEWU_EXIST = 501, 145 OH_QOS_GEWU_NOENT = 502, 146 OH_QOS_GEWU_NOSYS = 801, 147 OH_QOS_GEWU_FAULT = 901, 148 } OH_QoS_GewuErrorCode; 149 150 /** 151 * @param session The created session id 152 * @param error Error code of CreateSession 153 * - OH_QOS_GEWU_OK will be returned if the session is created successfully. 154 * - OH_QOS_GEWU_NOMEM will be returned if the system does not have sufficient memory to 155 * create the session. 156 * 157 * @since 20 158 */ 159 typedef struct { 160 OH_QoS_GewuSession session; 161 OH_QoS_GewuErrorCode error; 162 } OH_QoS_GewuCreateSessionResult; 163 164 /** 165 * @param request The created request id 166 * @param error Error code of request submission. 167 * - OH_QOS_GEWU_OK will be returned if the request is submitted successfully. 168 * - OH_QOS_GEWU_NOMEM will be returned if the system does not have sufficient memory to 169 * submit the request. 170 * 171 * @since 20 172 */ 173 typedef struct { 174 OH_QoS_GewuRequest request; 175 OH_QoS_GewuErrorCode error; 176 } OH_QoS_GewuSubmitRequestResult; 177 178 179 /** 180 * @brief Callback to receive response of the request. 181 * 182 * @param context The user context specified when submitting the request. 183 * @param reponse The json string of the response, including the following parameters: 184 * - message: A message that contains the following fields. 185 * - role: string. Must be "assistant". 186 * - content: string. The message generated by the model in response to user messages. 187 * - finish_reason: string or null. The reason the inference stopped. Possible values: 188 * - null: Not finished yet, only present in streaming mode. 189 * - "stop": The model stopped natually. 190 * - "abort": The inference request was aborted. 191 * - "length": The generated tokens reached the limit. 192 * 193 * @since 20 194 */ 195 typedef void (*OH_QoS_GewuOnResponse)(void* context, const char* response); 196 197 /** 198 * @brief Create a gewu session for inference. 199 * The lifecycle of the returned session object spans from the return of CreateSession 200 * to the call to DestroySession. 201 * 202 * json string of session attributes. 203 * 204 * The json string of session attributes include the following parameters 205 * - model: string. The directory of the model of the session. 206 * 207 * An example of json string of session attributes: 208 * @code{.json} 209 * { 210 * "model": "/data/storage/el2/base/files/qwen2/" 211 * } 212 * @endcode 213 * 214 * @param attributes The json string of session attributes. 215 * 216 * @return Result of CreateSession. 217 * 218 * @since 20 219 */ 220 OH_QoS_GewuCreateSessionResult OH_QoS_GewuCreateSession(const char* attributes); 221 222 /** 223 * @brief Destroy the specified session. 224 * It is recommended that the client shall wait until all ongoing requests are done before calling 225 * this interface to destroy the session. If there are remaining requests in the session when this 226 * interface is called, those requests will be aborted and no further responses for those requests 227 * will be sent to the client. 228 * Note that after calling this function successfully, the session cannot be used by the user code 229 * any more. 230 * 231 * @param session The session that will be destroyed. 232 * 233 * @return Error code. 234 * - OH_QOS_GEWU_OK will be returned if the session is destroyed successfully. 235 * - OH_QOS_GEWU_NOENT will be returned if the session is not found. 236 * 237 * @since 20 238 */ 239 OH_QoS_GewuErrorCode OH_QoS_GewuDestroySession(OH_QoS_GewuSession session); 240 241 /** 242 * @brief Abort the specified request. 243 * Note that after calling this function successfully, the client will not receive further responses 244 * for this request, and the request object cannot be used by the user code any more. 245 * 246 * @param session The session that the request was submitted through. 247 * @param request The request object. 248 * 249 * @return Error code. 250 * - OH_QOS_GEWU_OK will be returned if the request is aborted successfully. 251 * - OH_QOS_GEWU_NOENT will be returned if the request is not found. 252 * 253 * @since 20 254 */ 255 OH_QoS_GewuErrorCode OH_QoS_GewuAbortRequest(OH_QoS_GewuSession session, OH_QoS_GewuRequest request); 256 257 /** 258 * @brief Submit a request. 259 * 260 * json string of completion request. 261 * Completion request is a json string that specifies the following parameters: 262 * - messages: array. A list of messages. Each message contains the following fields: 263 * - role: string. The message type, which could be one of the following: 264 * - "developer": Developer-provided instructions. 265 * - "user": User-provided instructions. 266 * - "assistant": Message generated by the model in response to user messages. 267 * - content: string. The message content. 268 * - stream: boolean or null; optional. Enable streaming mode or not. If set to true, partial 269 * responses will be sent. If null or not set, defaults to nonstreaming mode. 270 * 271 * An example of completion request: 272 * @code{.json} 273 * { 274 * "messages": [ 275 * { 276 * "role": "developer", 277 * "content": "Your are a helpful assistant." 278 * }, 279 * { 280 * "role": "user", 281 * "content": "What is OpenHarmony" 282 * } 283 * ], 284 * "stream": true 285 * } 286 * @endcode 287 * 288 * @param session The session object that the request should be submitted through. 289 * @param request The json string of request. 290 * @param callback The callback to receive response. 291 * @param context The user context that should be passed to the response callback. 292 * 293 * @return Gewu request submission result. 294 * - OH_QOS_GEWU_OK will be returned if the request is accepted. 295 * - OH_QOS_GEWU_NOMEM will be returned if the system does not have sufficient memory 296 * to accept the request. 297 * 298 * @since 20 299 */ 300 OH_QoS_GewuSubmitRequestResult OH_QoS_GewuSubmitRequest(OH_QoS_GewuSession session, const char* request, 301 OH_QoS_GewuOnResponse callback, void* context); 302 303 #ifdef __cplusplus 304 }; 305 #endif 306 #endif // QOS_H 307 /** @} */ 308