* Copyright (c) 2023 Huawei Device Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
* @addtogroup FFRT
* @{
*
* @brief Provides Function Flow Runtime (FFRT) C APIs.
*
* FFRT is a task-based concurrent runtime library that automatically schedules
* tasks according to their dependencies, eliminating the need for manual
* thread management.
*
* @since 10
*/
* @file queue.h
*
* @brief Declares the queue interfaces in C.
*
* @library libffrt.z.so
* @kit FunctionFlowRuntimeKit
* @syscap SystemCapability.Resourceschedule.Ffrt.Core
* @since 10
*/
#ifndef FFRT_API_C_QUEUE_H
#define FFRT_API_C_QUEUE_H
#include <stdbool.h>
#include "type_def.h"
* @brief Enumerates the queue types.
*
* @since 12
*/
typedef enum {
ffrt_queue_serial,
ffrt_queue_concurrent,
ffrt_queue_max
} ffrt_queue_type_t;
* @brief Queue handle, which identifies different queues.
*
* @since 10
*/
typedef void* ffrt_queue_t;
* @brief Initializes a queue attribute.
*
* The queue attribute must later be destroyed by {@link ffrt_queue_attr_destroy}.
*
* @param attr Indicates a pointer to the queue attribute.
* @return `0` if the queue attribute is initialized;
* `-1` otherwise.
* @since 10
*/
FFRT_C_API int ffrt_queue_attr_init(ffrt_queue_attr_t* attr);
* @brief Destroys a queue attribute.
*
* The queue attribute must have been initialized by {@link ffrt_queue_attr_init}.
*
* @param attr Indicates a pointer to the queue attribute.
* @since 10
*/
FFRT_C_API void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr);
* @brief Sets the QoS for a queue attribute.
*
* @param attr Indicates a pointer to the queue attribute.
* @param qos Indicates the QoS level. See {@link ffrt_qos_t} for the value range.
* @since 10
*/
FFRT_C_API void ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos);
* @brief Gets the QoS of a queue attribute.
*
* @param attr Indicates a pointer to the queue attribute.
* @return The QoS level. See {@link ffrt_qos_t} for the value range.
* @since 10
*/
FFRT_C_API ffrt_qos_t ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr);
* @brief Sets the execution timeout of a queue attribute.
*
* @param attr Indicates a pointer to the queue attribute.
* @param timeout_us Indicates the queue task execution timeout, in microseconds.
* The lower limit is 1000 microseconds (1 ms); values below 1000 are clamped to 1000.
* @since 10
*/
FFRT_C_API void ffrt_queue_attr_set_timeout(ffrt_queue_attr_t* attr, uint64_t timeout_us);
* @brief Gets the execution timeout of a queue attribute.
*
* @param attr Indicates a pointer to the queue attribute.
* @return The queue task execution timeout, in microseconds.
* @since 10
*/
FFRT_C_API uint64_t ffrt_queue_attr_get_timeout(const ffrt_queue_attr_t* attr);
* @brief Sets the timeout callback of a queue attribute.
*
* The callback is triggered when a task in the queue runs longer than
* the timeout duration set by {@link ffrt_queue_attr_set_timeout}.
*
* @param attr Indicates a pointer to the queue attribute.
* @param f Indicates the queue timeout callback function.
* @since 10
*/
FFRT_C_API void ffrt_queue_attr_set_callback(ffrt_queue_attr_t* attr, ffrt_function_header_t* f);
* @brief Gets the timeout callback of a queue attribute.
*
* @param attr Indicates a pointer to the queue attribute.
* @return The queue task timeout callback function.
* @since 10
*/
FFRT_C_API ffrt_function_header_t* ffrt_queue_attr_get_callback(const ffrt_queue_attr_t* attr);
* @brief Sets the max concurrency of a concurrent queue attribute.
*
* @param attr Indicates a pointer to the queue attribute.
* @param max_concurrency Indicates the maximum number of tasks that a queue can execute concurrently.
* @since 12
*/
FFRT_C_API void ffrt_queue_attr_set_max_concurrency(ffrt_queue_attr_t* attr, const int max_concurrency);
* @brief Gets the max concurrency of a concurrent queue attribute.
*
* @param attr Indicates a pointer to the queue attribute.
* @return The maximum concurrency of the queue.
* @since 12
*/
FFRT_C_API int ffrt_queue_attr_get_max_concurrency(const ffrt_queue_attr_t* attr);
* @brief Sets the execution mode of a queue attribute.
*
* This interface specifies whether tasks in the queue are executed in coroutine mode or thread mode.
* By default, tasks are executed in coroutine mode.
* Set mode to `true` to enable thread-based execution.
*
* @param attr Indicates a pointer to the queue attribute.
* @param mode Indicates whether to enable thread-based execution mode.
* - `true`: Tasks are executed as native threads (thread mode).
* - `false`: Tasks are executed as coroutines (default).
* @since 20
*/
FFRT_C_API void ffrt_queue_attr_set_thread_mode(ffrt_queue_attr_t* attr, bool mode);
* @brief Gets the execution mode of a queue attribute.
*
* @param attr Indicates a pointer to the queue attribute.
* @return `true` if tasks are executed as native threads (thread mode);
* `false` if tasks are executed as coroutines (default).
* @since 20
*/
FFRT_C_API bool ffrt_queue_attr_get_thread_mode(const ffrt_queue_attr_t* attr);
* @brief Creates a queue.
*
* The queue must later be destroyed by {@link ffrt_queue_destroy} when no longer needed.
*
* @param type Indicates the queue type.
* `ffrt_queue_serial` is suitable when tasks must be executed in order;
* `ffrt_queue_concurrent` is suitable when tasks can be executed concurrently to improve throughput.
* @param name Indicates a pointer to the queue name.
* @param attr Indicates a pointer to the queue attribute.
* @return A non-null queue handle if the queue is created;
* a null pointer otherwise.
* @since 10
*/
FFRT_C_API ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr);
* @brief Destroys a queue.
*
* The queue must have been created by {@link ffrt_queue_create}. Destruction
* cancels tasks that have not yet started and blocks until any currently
* executing tasks complete.
*
* @param queue Indicates a queue handle.
* @since 10
*/
FFRT_C_API void ffrt_queue_destroy(ffrt_queue_t queue);
* @brief Submits a task to a queue.
*
* @param queue Indicates a queue handle.
* @param f Indicates a pointer to the task executor.
* @param attr Indicates a pointer to the task attribute.
* @see ffrt_queue_submit_h
* @since 10
*/
FFRT_C_API void ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr);
* @brief Submits a task to the queue, and obtains a task handle.
*
* @param queue Indicates a queue handle.
* @param f Indicates a pointer to the task executor.
* @param attr Indicates a pointer to the task attribute.
* @return A non-null task handle if the task is submitted;
* a null pointer otherwise.
* @see ffrt_queue_submit
* @since 10
*/
FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h(
ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr);
* @brief Submits a task to a queue, simplified from the {@link ffrt_queue_submit} interface.
*
* This interface wraps the provided task function and its argument into a task wrapper designed
* for queue submission (`ffrt_function_kind_queue`). During wrapper creation, the
* task destroy callback (after_func), which is intended to handle any post-execution cleanup,
* is set to NULL, thus omitting any additional cleanup actions. The resulting task wrapper is
* then submitted to the specified queue via the {@link ffrt_queue_submit} interface.
*
* @param queue Indicates a queue handle.
* @param func Indicates a task function to be executed.
* @param arg Indicates a pointer to the argument or closure data that will be passed to the task function.
* @param attr Indicates a pointer to the task attribute.
* @see ffrt_queue_submit
* @since 20
*/
FFRT_C_API void ffrt_queue_submit_f(ffrt_queue_t queue, ffrt_function_t func, void* arg, const ffrt_task_attr_t* attr);
* @brief Submits a task to a queue, and obtains a handle, simplified from the {@link ffrt_queue_submit_h} interface.
*
* This interface wraps the provided task function and its argument into a task wrapper designed
* for queue submission (`ffrt_function_kind_queue`). During wrapper creation, the
* task destroy callback (after_func), which is intended to handle any post-execution cleanup,
* is set to NULL, thus omitting any additional cleanup actions. The resulting task wrapper is
* then submitted to the specified queue via the {@link ffrt_queue_submit_h} interface.
*
* @param queue Indicates a queue handle.
* @param func Indicates a task function to be executed.
* @param arg Indicates a pointer to the argument or closure data that will be passed to the task function.
* @param attr Indicates a pointer to the task attribute.
* @return A non-null task handle if the task is submitted;
* a null pointer otherwise.
* @see ffrt_queue_submit_h
* @since 20
*/
FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h_f(
ffrt_queue_t queue, ffrt_function_t func, void* arg, const ffrt_task_attr_t* attr);
* @brief Waits until a task in the queue is complete.
*
* @param handle Indicates a task handle.
* @since 10
*/
FFRT_C_API void ffrt_queue_wait(ffrt_task_handle_t handle);
* @brief Cancels a task in the queue.
*
* Tasks that have already started executing cannot be canceled.
*
* @param handle Indicates a task handle.
* @return `0` if the task is canceled;
* `1` if the task has already been executed or removed from the queue;
* `-1` if `handle` is null.
* @since 10
*/
FFRT_C_API int ffrt_queue_cancel(ffrt_task_handle_t handle);
* @brief Gets the application main thread queue.
*
* @return The application main thread queue.
* @since 12
*/
FFRT_C_API ffrt_queue_t ffrt_get_main_queue(void);
* @brief Gets the application worker (ArkTS) thread queue.
*
* @return The application worker (ArkTS) thread queue.
* @deprecated since 18
* @since 12
*/
FFRT_C_API ffrt_queue_t ffrt_get_current_queue(void);
#endif
