1 // Copyright 2023 The Pigweed Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 4 // use this file except in compliance with the License. You may obtain a copy of 5 // the License at 6 // 7 // https://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, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations under 13 // the License. 14 #pragma once 15 16 #include "pw_async/dispatcher.h" 17 #include "pw_async/task.h" 18 #include "pw_sync/interrupt_spin_lock.h" 19 #include "pw_sync/lock_annotations.h" 20 #include "pw_sync/timed_thread_notification.h" 21 #include "pw_thread/thread_core.h" 22 23 namespace pw::async { 24 25 /// BasicDispatcher is a generic implementation of Dispatcher. 26 class BasicDispatcher final : public Dispatcher, public thread::ThreadCore { 27 public: 28 explicit BasicDispatcher() = default; 29 ~BasicDispatcher() override; 30 31 /// Execute all runnable tasks and return without waiting. 32 void RunUntilIdle(); 33 34 /// Run the dispatcher until Now() has reached `end_time`, executing all tasks 35 /// that come due before then. 36 void RunUntil(chrono::SystemClock::time_point end_time); 37 38 /// Run the dispatcher until `duration` has elapsed, executing all tasks that 39 /// come due in that period. 40 void RunFor(chrono::SystemClock::duration duration); 41 42 /// Stop processing tasks. If the dispatcher is serving a task loop, break out 43 /// of the loop, dequeue all waiting tasks, and call their TaskFunctions with 44 /// a PW_STATUS_CANCELLED status. If no task loop is being served, execute the 45 /// dequeueing procedure the next time the Dispatcher is run. 46 void RequestStop() PW_LOCKS_EXCLUDED(lock_); 47 48 // ThreadCore overrides: 49 50 /// Run the dispatcher until RequestStop() is called. Overrides 51 /// ThreadCore::Run() so that BasicDispatcher is compatible with 52 /// pw::thread::Thread. 53 void Run() override PW_LOCKS_EXCLUDED(lock_); 54 55 // Dispatcher overrides: 56 void Post(Task& task) override; 57 void PostAfter(Task& task, chrono::SystemClock::duration delay) override; 58 void PostAt(Task& task, chrono::SystemClock::time_point time) override; 59 void PostPeriodic(Task& task, 60 chrono::SystemClock::duration interval) override; 61 void PostPeriodicAt(Task& task, 62 chrono::SystemClock::duration interval, 63 chrono::SystemClock::time_point start_time) override; 64 bool Cancel(Task& task) override PW_LOCKS_EXCLUDED(lock_); 65 66 // VirtualSystemClock overrides: now()67 chrono::SystemClock::time_point now() override { 68 return chrono::SystemClock::now(); 69 } 70 71 private: 72 // Insert |task| into task_queue_ maintaining its min-heap property, keyed by 73 // |time_due|. 74 void PostTaskInternal(backend::NativeTask& task, 75 chrono::SystemClock::time_point time_due) 76 PW_EXCLUSIVE_LOCKS_REQUIRED(lock_); 77 78 // If no tasks are due, sleep until a notification is received, the next task 79 // comes due, or a timeout elapses; whichever occurs first. 80 void MaybeSleep() PW_EXCLUSIVE_LOCKS_REQUIRED(lock_); 81 82 // Dequeue and run each task that is due. 83 void ExecuteDueTasks() PW_EXCLUSIVE_LOCKS_REQUIRED(lock_); 84 85 // Dequeue each task and call each TaskFunction with a PW_STATUS_CANCELLED 86 // status. 87 void DrainTaskQueue() PW_EXCLUSIVE_LOCKS_REQUIRED(lock_); 88 89 sync::InterruptSpinLock lock_; 90 sync::TimedThreadNotification timed_notification_; 91 bool stop_requested_ PW_GUARDED_BY(lock_) = false; 92 // A priority queue of scheduled Tasks sorted by earliest due times first. 93 IntrusiveList<backend::NativeTask> task_queue_ PW_GUARDED_BY(lock_); 94 }; 95 96 } // namespace pw::async 97