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 #ifndef META_INTERFACE_ITASKQUEUE_H 16 #define META_INTERFACE_ITASKQUEUE_H 17 18 #include <meta/base/time_span.h> 19 #include <meta/base/types.h> 20 #include <meta/interface/intf_callable.h> 21 #include <meta/interface/intf_clock.h> 22 #include <meta/interface/intf_future.h> 23 24 META_BEGIN_NAMESPACE() 25 26 META_REGISTER_INTERFACE(ITaskQueueTask, "64fd1333-f59b-4f96-901c-1a7efa50387c") 27 META_REGISTER_INTERFACE(ITaskQueueWaitableTask, "cf2ef384-b14f-4bb7-acda-2c4b0bfa4917") 28 META_REGISTER_INTERFACE(ITaskScheduleInfo, "d9fe0fb1-84dd-4210-bf33-6fdbe650615b") 29 META_REGISTER_INTERFACE(ITaskQueue, "138b0a6d-4a97-4ad6-bba3-1bee7cc36d58") 30 META_REGISTER_INTERFACE(IPollingTaskQueue, "16e007c1-f8f8-4e9d-b5d7-d7016f9c54d3") 31 META_REGISTER_INTERFACE(IThreadedTaskQueue, "42be1ec0-5711-4377-aa40-5270be31ad7d") 32 33 /** 34 * @brief The ITaskQueueTask interface defines the interface which a class 35 * must implement to be schedulable in a task queue. 36 */ 37 class ITaskQueueTask : public META_NS::ICallable { 38 META_INTERFACE(META_NS::ICallable, ITaskQueueTask); 39 40 public: 41 using FunctionType = bool(); 42 /** 43 * @brief Called by the task queue to execute the task. 44 * @return If Invoke returns true, the task is rescheduled in the same task queue. 45 */ 46 virtual bool Invoke() = 0; 47 }; 48 49 /** 50 * @brief The ITaskQueueWaitableTask defines the interface which a class 51 * must implement to be schedulable as a waitable task in a task queue. 52 */ 53 class ITaskQueueWaitableTask : public META_NS::ICallable { 54 META_INTERFACE(META_NS::ICallable, ITaskQueueWaitableTask); 55 56 public: 57 using FunctionType = IAny::Ptr(); 58 /** 59 * @brief Called by the task queue to execute the task. 60 * @return Result of the task. 61 */ 62 virtual IAny::Ptr Invoke() = 0; 63 }; 64 65 /** 66 * @brief The ITaskQueue interface defines the interface for a class which 67 * implements a task queue where tasks can be scheduled. 68 */ 69 class ITaskQueue : public CORE_NS::IInterface { 70 META_INTERFACE(CORE_NS::IInterface, ITaskQueue); 71 72 public: 73 using CallableType = ITaskQueueTask; 74 using Token = const void*; 75 /** 76 * @brief Add a task to the task queue and execute the task as soon as possible. 77 * @param p The task to execute. 78 * @return Queue token for the task. The token can be used to cancel the task. 79 */ 80 virtual Token AddTask(ITaskQueueTask::Ptr p) = 0; 81 /** 82 * @brief Add a task to the task queue and execute it after a given delay. 83 * @note The delay defines the minimum delay after which the task is executed. 84 * Depending on the task queue implementation and platform specifics the 85 * task may actually be executed substantially later than the given delay. 86 * @param p The task to execute. 87 * @param delay Do not run the task earlier than this delay. 88 * @return Queue token for the task. The token can be used to cancel the task. 89 */ 90 virtual Token AddTask(ITaskQueueTask::Ptr p, const TimeSpan& delay) = 0; 91 /** 92 * @brief Add a task to the task queue and return an object which can be 93 * used to wait for the task to complete. 94 * @param p The task to execute. 95 * @return A future object which can be waited on. 96 */ 97 virtual IFuture::Ptr AddWaitableTask(ITaskQueueWaitableTask::Ptr p) = 0; 98 /** 99 * @brief Cancel a task. 100 * @note If task is already running, waits for completion (unless the call to cancel comes from the 101 * task itself). 102 * If the task has not been started yet, it is removed from the queue immediately. 103 * @param token The queue token of the task to cancel. 104 */ 105 virtual void CancelTask(Token) = 0; 106 }; 107 108 /** 109 * @brief The IPollingTaskQueue interface defines an interface to be implemented 110 * by task queues which must be manually processed by the application. 111 */ 112 class IPollingTaskQueue : public ITaskQueue { 113 META_INTERFACE(ITaskQueue, IPollingTaskQueue); 114 115 public: 116 /** 117 * @brief Execute all queued tasks. The function returns once all of the tests 118 * have been executed. 119 * @note If a task reschedules itself while being run, it will not be run a second 120 * time until ProcessTasks() is called again. 121 */ 122 virtual void ProcessTasks() = 0; 123 }; 124 125 /** 126 * @brief The IThreadedTaskQueue interface defines an interface to be implemented 127 * by tasks queues which run their tasks in a separate thread. 128 */ 129 class IThreadedTaskQueue : public ITaskQueue { 130 META_INTERFACE(ITaskQueue, IThreadedTaskQueue); 131 132 public: 133 /** Interface defined for completeness 134 Possibly add methods to wait for the queue empty */ 135 }; 136 137 /** 138 * @brief The ITaskScheduleInfo interface is used to set the task queue where this token is 139 * scheduled to run with the token. 140 */ 141 class ITaskScheduleInfo : public CORE_NS::IInterface { 142 META_INTERFACE(CORE_NS::IInterface, ITaskScheduleInfo); 143 144 public: 145 virtual void SetQueueAndToken(const ITaskQueue::Ptr&, ITaskQueue::Token) = 0; 146 }; 147 148 /** Built-in task queue implementations */ 149 META_REGISTER_CLASS(PollingTaskQueue, "d4a5944e-db40-4603-834e-457a21123e2c", ObjectCategoryBits::NO_CATEGORY) 150 META_REGISTER_CLASS(ThreadedTaskQueue, "009bf37a-d490-4a01-b7bb-f3365cc0a8da", ObjectCategoryBits::NO_CATEGORY) 151 152 META_END_NAMESPACE() 153 154 #endif // META_INTERFACE_ITASKQUEUE_H 155