/* * 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 ffrt provides APIs. * * * @syscap SystemCapability.Resourceschedule.Ffrt.Core * * @since 10 */ /** * @file task.h * * @brief Declares the task interfaces in C. * * @syscap SystemCapability.Resourceschedule.Ffrt.Core * @since 10 * @version 1.0 */ #ifndef FFRT_API_C_TASK_H #define FFRT_API_C_TASK_H #include #include "type_def.h" /** * @brief Initializes a task attribute. * * @param attr Indicates a pointer to the task attribute. * @return Returns 0 if the task attribute is initialized; returns -1 otherwise. * @since 10 * @version 1.0 */ FFRT_C_API int ffrt_task_attr_init(ffrt_task_attr_t* attr); /** * @brief Sets a task name. * * @param attr Indicates a pointer to the task attribute. * @param name Indicates a pointer to the task name. * @since 10 * @version 1.0 */ FFRT_C_API void ffrt_task_attr_set_name(ffrt_task_attr_t* attr, const char* name); /** * @brief Obtains a task name. * * @param attr Indicates a pointer to the task attribute. * @return Returns a non-null pointer to the task name if the name is obtained; returns a null pointer otherwise. * @since 10 * @version 1.0 */ FFRT_C_API const char* ffrt_task_attr_get_name(const ffrt_task_attr_t* attr); /** * @brief Destroys a task attribute. * * @param attr Indicates a pointer to the task attribute. * @since 10 * @version 1.0 */ FFRT_C_API void ffrt_task_attr_destroy(ffrt_task_attr_t* attr); /** * @brief Sets the QoS for a task attribute. * * @param attr Indicates a pointer to the task attribute. * @param qos Indicates the QoS. * @since 10 * @version 1.0 */ FFRT_C_API void ffrt_task_attr_set_qos(ffrt_task_attr_t* attr, ffrt_qos_t qos); /** * @brief Obtains the QoS of a task attribute. * * @param attr Indicates a pointer to the task attribute. * @return Returns the QoS, which is ffrt_qos_default by default. * @since 10 * @version 1.0 */ FFRT_C_API ffrt_qos_t ffrt_task_attr_get_qos(const ffrt_task_attr_t* attr); /** * @brief Sets the task delay time. * * @param attr Indicates a pointer to the task attribute. * @param delay_us Indicates the delay time, in microseconds. * @since 10 * @version 1.0 */ FFRT_C_API void ffrt_task_attr_set_delay(ffrt_task_attr_t* attr, uint64_t delay_us); /** * @brief Obtains the task delay time. * * @param attr Indicates a pointer to the task attribute. * @return Returns the delay time. * @since 10 * @version 1.0 */ FFRT_C_API uint64_t ffrt_task_attr_get_delay(const ffrt_task_attr_t* attr); /** * @brief Sets the task priority. * * @param attr Indicates a pointer to the task attribute. * @param priority Indicates the execute priority of concurrent queue task. * @since 12 * @version 1.0 */ FFRT_C_API void ffrt_task_attr_set_queue_priority(ffrt_task_attr_t* attr, ffrt_queue_priority_t priority); /** * @brief Obtains the task priority. * * @param attr Indicates a pointer to the task attribute. * @return Returns the priority of concurrent queue task. * @since 12 * @version 1.0 */ FFRT_C_API ffrt_queue_priority_t ffrt_task_attr_get_queue_priority(const ffrt_task_attr_t* attr); /** * @brief Sets the task stack size. * * @param attr Indicates a pointer to the task attribute. * @param size Indicates the task stack size, unit is byte. * @since 12 * @version 1.0 */ FFRT_C_API void ffrt_task_attr_set_stack_size(ffrt_task_attr_t* attr, uint64_t size); /** * @brief Obtains the task stack size. * * @param attr Indicates a pointer to the task attribute. * @return Returns the task stack size, unit is byte. * @since 12 * @version 1.0 */ FFRT_C_API uint64_t ffrt_task_attr_get_stack_size(const ffrt_task_attr_t* attr); /** * @brief Set the task schedule timeout. * * @param attr Indicates a pointer to the task attribute. * @param timeout_us task scheduler timeout. * @version 1.0 */ FFRT_C_API void ffrt_task_attr_set_timeout(ffrt_task_attr_t* attr, uint64_t timeout_us); /** * @brief Get the task schedule timeout. * * @param attr Indicates a pointer to the task attribute. * @return Returns the task schedule timeout. * @version 1.0 */ FFRT_C_API uint64_t ffrt_task_attr_get_timeout(const ffrt_task_attr_t* attr); /** * @brief Updates the QoS of this task. * * @param qos Indicates the new QoS. * @return Returns 0 if the QoS is updated; returns -1 otherwise. * @since 10 * @version 1.0 */ FFRT_C_API int ffrt_this_task_update_qos(ffrt_qos_t qos); /** * @brief Obtains the qos of this task. * * @return Returns the task qos. * @since 12 * @version 1.0 */ FFRT_C_API ffrt_qos_t ffrt_this_task_get_qos(); /** * @brief Obtains the ID of this task. * * @return Returns the task ID. * @since 10 * @version 1.0 */ FFRT_C_API uint64_t ffrt_this_task_get_id(void); /** * @brief Applies for memory for the function execution structure. * * @param kind Indicates the type of the function execution structure, which can be common or queue. * @return Returns a non-null pointer if the memory is allocated; returns a null pointer otherwise. * @since 10 * @version 1.0 */ FFRT_C_API void *ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_t kind); /** * @brief Submits a task. * * @param f Indicates a pointer to the task executor. * @param in_deps Indicates a pointer to the input dependencies. * @param out_deps Indicates a pointer to the output dependencies. * @param attr Indicates a pointer to the task attribute. * @since 10 * @version 1.0 */ FFRT_C_API void ffrt_submit_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr); /** * @brief Submits a task, and obtains a task handle. * * @param f Indicates a pointer to the task executor. * @param in_deps Indicates a pointer to the input dependencies. * @param out_deps Indicates a pointer to the output dependencies. * @param attr Indicates a pointer to the task attribute. * @return Returns a non-null task handle if the task is submitted; returns a null pointer otherwise. * @since 10 * @version 1.0 */ FFRT_C_API ffrt_task_handle_t ffrt_submit_h_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr); /** * @brief increase reference count of task handle. * * @param handle Indicates a task handle. * @return return the task handle original reference count. * @since 12 * @version 1.0 */ FFRT_C_API uint32_t ffrt_task_handle_inc_ref(ffrt_task_handle_t handle); /** * @brief decrease reference count of task handle. * * @param handle Indicates a task handle. * @return return the task handle original reference count. * @since 12 * @version 1.0 */ FFRT_C_API uint32_t ffrt_task_handle_dec_ref(ffrt_task_handle_t handle); /** * @brief Destroys a task handle. * * @param handle Indicates a task handle. * @since 10 * @version 1.0 */ FFRT_C_API void ffrt_task_handle_destroy(ffrt_task_handle_t handle); /** * @brief Waits until the dependent tasks are complete. * * @param deps Indicates a pointer to the dependent tasks. * @since 10 * @version 1.0 */ FFRT_C_API void ffrt_wait_deps(const ffrt_deps_t* deps); /** * @brief Waits until all submitted tasks are complete. * * @since 10 * @version 1.0 */ FFRT_C_API void ffrt_wait(void); /** * @brief Sets the thread stack size of a specified QoS level. * * @param qos Indicates the QoS. * @param stack_size Indicates worker thread stack size. * @since 10 * @version 1.0 */ FFRT_C_API ffrt_error_t ffrt_set_worker_stack_size(ffrt_qos_t qos, size_t stack_size); /** * @brief get gid from task handle. * * @param handle Indicates a task handle. * @return Return gid. * @since 10 * @version 1.0 */ FFRT_C_API uint64_t ffrt_task_handle_get_id(ffrt_task_handle_t handle); #endif