Janis Danisevskis | 93927dd | 2020-12-23 12:23:08 -0800 | [diff] [blame] | 1 | // Copyright 2020, The Android Open Source Project |
| 2 | // |
| 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 | //! This module implements the handling of async tasks. |
| 16 | //! The worker thread has a high priority and a low priority queue. Adding a job to either |
| 17 | //! will cause one thread to be spawned if none exists. As a compromise between performance |
| 18 | //! and resource consumption, the thread will linger for about 30 seconds after it has |
| 19 | //! processed all tasks before it terminates. |
| 20 | //! Note that low priority tasks are processed only when the high priority queue is empty. |
| 21 | |
Janis Danisevskis | 40f0e6b | 2021-02-10 15:48:44 -0800 | [diff] [blame] | 22 | use std::{any::Any, any::TypeId, time::Duration}; |
Janis Danisevskis | 93927dd | 2020-12-23 12:23:08 -0800 | [diff] [blame] | 23 | use std::{ |
Janis Danisevskis | 40f0e6b | 2021-02-10 15:48:44 -0800 | [diff] [blame] | 24 | collections::{HashMap, VecDeque}, |
Janis Danisevskis | 93927dd | 2020-12-23 12:23:08 -0800 | [diff] [blame] | 25 | sync::Arc, |
| 26 | sync::{Condvar, Mutex, MutexGuard}, |
| 27 | thread, |
| 28 | }; |
| 29 | |
| 30 | #[derive(Debug, PartialEq, Eq)] |
| 31 | enum State { |
| 32 | Exiting, |
| 33 | Running, |
| 34 | } |
| 35 | |
Janis Danisevskis | 40f0e6b | 2021-02-10 15:48:44 -0800 | [diff] [blame] | 36 | /// The Shelf allows async tasks to store state across invocations. |
| 37 | /// Note: Store elves at your own peril ;-). |
| 38 | #[derive(Debug, Default)] |
| 39 | pub struct Shelf(HashMap<TypeId, Box<dyn Any + Send>>); |
| 40 | |
| 41 | impl Shelf { |
| 42 | /// Get a reference to the shelved data of type T. Returns Some if the data exists. |
| 43 | pub fn get_downcast_ref<T: Any + Send>(&self) -> Option<&T> { |
| 44 | self.0.get(&TypeId::of::<T>()).and_then(|v| v.downcast_ref::<T>()) |
| 45 | } |
| 46 | |
| 47 | /// Get a mutable reference to the shelved data of type T. If a T was inserted using put, |
| 48 | /// get_mut, or get_or_put_with. |
| 49 | pub fn get_downcast_mut<T: Any + Send>(&mut self) -> Option<&mut T> { |
| 50 | self.0.get_mut(&TypeId::of::<T>()).and_then(|v| v.downcast_mut::<T>()) |
| 51 | } |
| 52 | |
| 53 | /// Remove the entry of the given type and returns the stored data if it existed. |
| 54 | pub fn remove_downcast_ref<T: Any + Send>(&mut self) -> Option<T> { |
| 55 | self.0.remove(&TypeId::of::<T>()).and_then(|v| v.downcast::<T>().ok().map(|b| *b)) |
| 56 | } |
| 57 | |
| 58 | /// Puts data `v` on the shelf. If there already was an entry of type T it is returned. |
| 59 | pub fn put<T: Any + Send>(&mut self, v: T) -> Option<T> { |
| 60 | self.0 |
| 61 | .insert(TypeId::of::<T>(), Box::new(v) as Box<dyn Any + Send>) |
| 62 | .and_then(|v| v.downcast::<T>().ok().map(|b| *b)) |
| 63 | } |
| 64 | |
| 65 | /// Gets a mutable reference to the entry of the given type and default creates it if necessary. |
| 66 | /// The type must implement Default. |
| 67 | pub fn get_mut<T: Any + Send + Default>(&mut self) -> &mut T { |
| 68 | self.0 |
| 69 | .entry(TypeId::of::<T>()) |
| 70 | .or_insert_with(|| Box::new(T::default()) as Box<dyn Any + Send>) |
| 71 | .downcast_mut::<T>() |
| 72 | .unwrap() |
| 73 | } |
Janis Danisevskis | 7e8b462 | 2021-02-13 10:01:59 -0800 | [diff] [blame] | 74 | |
| 75 | /// Gets a mutable reference to the entry of the given type or creates it using the init |
| 76 | /// function. Init is not executed if the entry already existed. |
| 77 | pub fn get_or_put_with<T: Any + Send, F>(&mut self, init: F) -> &mut T |
| 78 | where |
| 79 | F: FnOnce() -> T, |
| 80 | { |
| 81 | self.0 |
| 82 | .entry(TypeId::of::<T>()) |
| 83 | .or_insert_with(|| Box::new(init()) as Box<dyn Any + Send>) |
| 84 | .downcast_mut::<T>() |
| 85 | .unwrap() |
| 86 | } |
Janis Danisevskis | 40f0e6b | 2021-02-10 15:48:44 -0800 | [diff] [blame] | 87 | } |
| 88 | |
Janis Danisevskis | 93927dd | 2020-12-23 12:23:08 -0800 | [diff] [blame] | 89 | struct AsyncTaskState { |
| 90 | state: State, |
| 91 | thread: Option<thread::JoinHandle<()>>, |
Janis Danisevskis | 40f0e6b | 2021-02-10 15:48:44 -0800 | [diff] [blame] | 92 | hi_prio_req: VecDeque<Box<dyn FnOnce(&mut Shelf) + Send>>, |
| 93 | lo_prio_req: VecDeque<Box<dyn FnOnce(&mut Shelf) + Send>>, |
| 94 | /// The store allows tasks to store state across invocations. It is passed to each invocation |
| 95 | /// of each task. Tasks need to cooperate on the ids they use for storing state. |
| 96 | shelf: Option<Shelf>, |
Janis Danisevskis | 93927dd | 2020-12-23 12:23:08 -0800 | [diff] [blame] | 97 | } |
| 98 | |
| 99 | /// AsyncTask spawns one worker thread on demand to process jobs inserted into |
Janis Danisevskis | 7e8b462 | 2021-02-13 10:01:59 -0800 | [diff] [blame] | 100 | /// a low and a high priority work queue. The queues are processed FIFO, and low |
| 101 | /// priority queue is processed if the high priority queue is empty. |
| 102 | /// Note: Because there is only one worker thread at a time for a given AsyncTask instance, |
| 103 | /// all scheduled requests are guaranteed to be serialized with respect to one another. |
Janis Danisevskis | 93927dd | 2020-12-23 12:23:08 -0800 | [diff] [blame] | 104 | pub struct AsyncTask { |
| 105 | state: Arc<(Condvar, Mutex<AsyncTaskState>)>, |
| 106 | } |
| 107 | |
| 108 | impl Default for AsyncTask { |
| 109 | fn default() -> Self { |
| 110 | Self { |
| 111 | state: Arc::new(( |
| 112 | Condvar::new(), |
| 113 | Mutex::new(AsyncTaskState { |
| 114 | state: State::Exiting, |
| 115 | thread: None, |
| 116 | hi_prio_req: VecDeque::new(), |
| 117 | lo_prio_req: VecDeque::new(), |
Janis Danisevskis | 40f0e6b | 2021-02-10 15:48:44 -0800 | [diff] [blame] | 118 | shelf: None, |
Janis Danisevskis | 93927dd | 2020-12-23 12:23:08 -0800 | [diff] [blame] | 119 | }), |
| 120 | )), |
| 121 | } |
| 122 | } |
| 123 | } |
| 124 | |
| 125 | impl AsyncTask { |
| 126 | /// Adds a job to the high priority queue. High priority jobs are completed before |
| 127 | /// low priority jobs and can also overtake low priority jobs. But they cannot |
| 128 | /// preempt them. |
| 129 | pub fn queue_hi<F>(&self, f: F) |
| 130 | where |
Janis Danisevskis | 40f0e6b | 2021-02-10 15:48:44 -0800 | [diff] [blame] | 131 | F: for<'r> FnOnce(&'r mut Shelf) + Send + 'static, |
Janis Danisevskis | 93927dd | 2020-12-23 12:23:08 -0800 | [diff] [blame] | 132 | { |
| 133 | self.queue(f, true) |
| 134 | } |
| 135 | |
| 136 | /// Adds a job to the low priority queue. Low priority jobs are completed after |
| 137 | /// high priority. And they are not executed as long as high priority jobs are |
| 138 | /// present. Jobs always run to completion and are never preempted by high |
| 139 | /// priority jobs. |
| 140 | pub fn queue_lo<F>(&self, f: F) |
| 141 | where |
Janis Danisevskis | 40f0e6b | 2021-02-10 15:48:44 -0800 | [diff] [blame] | 142 | F: FnOnce(&mut Shelf) + Send + 'static, |
Janis Danisevskis | 93927dd | 2020-12-23 12:23:08 -0800 | [diff] [blame] | 143 | { |
| 144 | self.queue(f, false) |
| 145 | } |
| 146 | |
| 147 | fn queue<F>(&self, f: F, hi_prio: bool) |
| 148 | where |
Janis Danisevskis | 40f0e6b | 2021-02-10 15:48:44 -0800 | [diff] [blame] | 149 | F: for<'r> FnOnce(&'r mut Shelf) + Send + 'static, |
Janis Danisevskis | 93927dd | 2020-12-23 12:23:08 -0800 | [diff] [blame] | 150 | { |
| 151 | let (ref condvar, ref state) = *self.state; |
| 152 | let mut state = state.lock().unwrap(); |
| 153 | if hi_prio { |
| 154 | state.hi_prio_req.push_back(Box::new(f)); |
| 155 | } else { |
| 156 | state.lo_prio_req.push_back(Box::new(f)); |
| 157 | } |
| 158 | |
| 159 | if state.state != State::Running { |
| 160 | self.spawn_thread(&mut state); |
| 161 | } |
| 162 | drop(state); |
| 163 | condvar.notify_all(); |
| 164 | } |
| 165 | |
| 166 | fn spawn_thread(&self, state: &mut MutexGuard<AsyncTaskState>) { |
| 167 | if let Some(t) = state.thread.take() { |
| 168 | t.join().expect("AsyncTask panicked."); |
| 169 | } |
| 170 | |
| 171 | let cloned_state = self.state.clone(); |
| 172 | |
| 173 | state.thread = Some(thread::spawn(move || { |
| 174 | let (ref condvar, ref state) = *cloned_state; |
Janis Danisevskis | 40f0e6b | 2021-02-10 15:48:44 -0800 | [diff] [blame] | 175 | // When the worker starts, it takes the shelf and puts it on the stack. |
| 176 | let mut shelf = state.lock().unwrap().shelf.take().unwrap_or_default(); |
Janis Danisevskis | 93927dd | 2020-12-23 12:23:08 -0800 | [diff] [blame] | 177 | loop { |
| 178 | if let Some(f) = { |
| 179 | let (mut state, timeout) = condvar |
| 180 | .wait_timeout_while( |
| 181 | state.lock().unwrap(), |
| 182 | Duration::from_secs(30), |
| 183 | |state| state.hi_prio_req.is_empty() && state.lo_prio_req.is_empty(), |
| 184 | ) |
| 185 | .unwrap(); |
| 186 | match ( |
| 187 | state.hi_prio_req.pop_front(), |
| 188 | state.lo_prio_req.is_empty(), |
| 189 | timeout.timed_out(), |
| 190 | ) { |
| 191 | (Some(f), _, _) => Some(f), |
| 192 | (None, false, _) => state.lo_prio_req.pop_front(), |
| 193 | (None, true, true) => { |
Janis Danisevskis | 40f0e6b | 2021-02-10 15:48:44 -0800 | [diff] [blame] | 194 | // When the worker exits it puts the shelf back into the shared |
| 195 | // state for the next worker to use. So state is preserved not |
| 196 | // only across invocations but also across worker thread shut down. |
| 197 | state.shelf = Some(shelf); |
Janis Danisevskis | 93927dd | 2020-12-23 12:23:08 -0800 | [diff] [blame] | 198 | state.state = State::Exiting; |
| 199 | break; |
| 200 | } |
| 201 | (None, true, false) => None, |
| 202 | } |
| 203 | } { |
Janis Danisevskis | 40f0e6b | 2021-02-10 15:48:44 -0800 | [diff] [blame] | 204 | f(&mut shelf) |
Janis Danisevskis | 93927dd | 2020-12-23 12:23:08 -0800 | [diff] [blame] | 205 | } |
| 206 | } |
| 207 | })); |
| 208 | state.state = State::Running; |
| 209 | } |
| 210 | } |
David Drysdale | 2d3e501 | 2021-02-23 12:30:27 +0000 | [diff] [blame] | 211 | |
| 212 | #[cfg(test)] |
| 213 | mod tests { |
David Drysdale | bddc3ae | 2021-02-23 16:21:46 +0000 | [diff] [blame^] | 214 | use super::{AsyncTask, Shelf}; |
| 215 | use std::sync::mpsc::channel; |
David Drysdale | 2d3e501 | 2021-02-23 12:30:27 +0000 | [diff] [blame] | 216 | |
| 217 | #[test] |
| 218 | fn test_shelf() { |
| 219 | let mut shelf = Shelf::default(); |
| 220 | |
| 221 | let s = "A string".to_string(); |
| 222 | assert_eq!(shelf.put(s), None); |
| 223 | |
| 224 | let s2 = "Another string".to_string(); |
| 225 | assert_eq!(shelf.put(s2), Some("A string".to_string())); |
| 226 | |
| 227 | // Put something of a different type on the shelf. |
| 228 | #[derive(Debug, PartialEq, Eq)] |
| 229 | struct Elf { |
| 230 | pub name: String, |
| 231 | } |
| 232 | let e1 = Elf { name: "Glorfindel".to_string() }; |
| 233 | assert_eq!(shelf.put(e1), None); |
| 234 | |
| 235 | // The String value is still on the shelf. |
| 236 | let s3 = shelf.get_downcast_ref::<String>().unwrap(); |
| 237 | assert_eq!(s3, "Another string"); |
| 238 | |
| 239 | // As is the Elf. |
| 240 | { |
| 241 | let e2 = shelf.get_downcast_mut::<Elf>().unwrap(); |
| 242 | assert_eq!(e2.name, "Glorfindel"); |
| 243 | e2.name = "Celeborn".to_string(); |
| 244 | } |
| 245 | |
| 246 | // Take the Elf off the shelf. |
| 247 | let e3 = shelf.remove_downcast_ref::<Elf>().unwrap(); |
| 248 | assert_eq!(e3.name, "Celeborn"); |
| 249 | |
| 250 | assert_eq!(shelf.remove_downcast_ref::<Elf>(), None); |
| 251 | |
| 252 | // No u64 value has been put on the shelf, so getting one gives the default value. |
| 253 | { |
| 254 | let i = shelf.get_mut::<u64>(); |
| 255 | assert_eq!(*i, 0); |
| 256 | *i = 42; |
| 257 | } |
| 258 | let i2 = shelf.get_downcast_ref::<u64>().unwrap(); |
| 259 | assert_eq!(*i2, 42); |
| 260 | |
| 261 | // No i32 value has ever been seen near the shelf. |
| 262 | assert_eq!(shelf.get_downcast_ref::<i32>(), None); |
| 263 | assert_eq!(shelf.get_downcast_mut::<i32>(), None); |
| 264 | assert_eq!(shelf.remove_downcast_ref::<i32>(), None); |
| 265 | } |
David Drysdale | bddc3ae | 2021-02-23 16:21:46 +0000 | [diff] [blame^] | 266 | |
| 267 | #[test] |
| 268 | fn test_async_task() { |
| 269 | let at = AsyncTask::default(); |
| 270 | |
| 271 | // First queue up a job that blocks until we release it, to avoid |
| 272 | // unpredictable synchronization. |
| 273 | let (start_sender, start_receiver) = channel(); |
| 274 | at.queue_hi(move |shelf| { |
| 275 | start_receiver.recv().unwrap(); |
| 276 | // Put a trace vector on the shelf |
| 277 | shelf.put(Vec::<String>::new()); |
| 278 | }); |
| 279 | |
| 280 | // Queue up some high-priority and low-priority jobs. |
| 281 | for i in 0..3 { |
| 282 | let j = i; |
| 283 | at.queue_lo(move |shelf| { |
| 284 | let trace = shelf.get_mut::<Vec<String>>(); |
| 285 | trace.push(format!("L{}", j)); |
| 286 | }); |
| 287 | let j = i; |
| 288 | at.queue_hi(move |shelf| { |
| 289 | let trace = shelf.get_mut::<Vec<String>>(); |
| 290 | trace.push(format!("H{}", j)); |
| 291 | }); |
| 292 | } |
| 293 | |
| 294 | // Finally queue up a low priority job that emits the trace. |
| 295 | let (trace_sender, trace_receiver) = channel(); |
| 296 | at.queue_lo(move |shelf| { |
| 297 | let trace = shelf.get_downcast_ref::<Vec<String>>().unwrap(); |
| 298 | trace_sender.send(trace.clone()).unwrap(); |
| 299 | }); |
| 300 | |
| 301 | // Ready, set, go. |
| 302 | start_sender.send(()).unwrap(); |
| 303 | let trace = trace_receiver.recv().unwrap(); |
| 304 | |
| 305 | assert_eq!(trace, vec!["H0", "H1", "H2", "L0", "L1", "L2"]); |
| 306 | } |
| 307 | |
| 308 | #[test] |
| 309 | #[should_panic] |
| 310 | fn test_async_task_panic() { |
| 311 | let at = AsyncTask::default(); |
| 312 | at.queue_hi(|_shelf| { |
| 313 | panic!("Panic from queued job"); |
| 314 | }); |
| 315 | // Queue another job afterwards to ensure that the async thread gets joined. |
| 316 | let (done_sender, done_receiver) = channel(); |
| 317 | at.queue_hi(move |_shelf| { |
| 318 | done_sender.send(()).unwrap(); |
| 319 | }); |
| 320 | done_receiver.recv().unwrap(); |
| 321 | } |
David Drysdale | 2d3e501 | 2021-02-23 12:30:27 +0000 | [diff] [blame] | 322 | } |