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