| 1 |
/* |
| 2 |
* Copyright (C) 2015 The Android Open Source Project |
| 3 |
* |
| 4 |
* Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 |
* you may not use this file except in compliance with the License. |
| 6 |
* You may obtain a copy of the License at |
| 7 |
* |
| 8 |
* http://www.apache.org/licenses/LICENSE-2.0 |
| 9 |
* |
| 10 |
* Unless required by applicable law or agreed to in writing, software |
| 11 |
* distributed under the License is distributed on an "AS IS" BASIS, |
| 12 |
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 |
* See the License for the specific language governing permissions and |
| 14 |
* limitations under the License. |
| 15 |
*/ |
| 16 |
|
| 17 |
#pragma once |
| 18 |
|
| 19 |
#include <deque> |
| 20 |
#include <functional> |
| 21 |
#include <mutex> |
| 22 |
|
| 23 |
/** |
| 24 |
* A simple thread-safe job queue. |
| 25 |
* |
| 26 |
* JobQueue allows to push "jobs" (i.e.: code and its state) into a queue and later execute these |
| 27 |
* job in FIFO order, possibly (and generally) from another thread. |
| 28 |
* |
| 29 |
* example: |
| 30 |
* @code |
| 31 |
* using utils::JobQueue; |
| 32 |
* static JobQueue sJobs; |
| 33 |
* |
| 34 |
* struct Foo { |
| 35 |
* void bar(); |
| 36 |
* void baz(int); |
| 37 |
* } foo; |
| 38 |
* |
| 39 |
* sJobs.push([]() { |
| 40 |
* // one can use a lambda |
| 41 |
* }); |
| 42 |
* |
| 43 |
* sJobs.push(&Foo::bar, foo) { |
| 44 |
* // ...or a method of a class |
| 45 |
* } |
| 46 |
* |
| 47 |
* sJobs.push(&Foo::bar, baz, 42) { |
| 48 |
* // ... even a method with arguments |
| 49 |
* } |
| 50 |
* |
| 51 |
* // Later, in another thread for instance... |
| 52 |
* |
| 53 |
* // empty the queue and runs all jobs in FIFO order |
| 54 |
* sJobs.runAllJobs(); |
| 55 |
* |
| 56 |
* // runs the oldest job if there is one |
| 57 |
* bool got_one = sJobs.runJobIfAny(); |
| 58 |
* |
| 59 |
* // dequeue a job, but run it manually. |
| 60 |
* Job job(sJobs.pop()); |
| 61 |
* if (job) { |
| 62 |
* job(); |
| 63 |
* } |
| 64 |
* |
| 65 |
* @endcode |
| 66 |
* |
| 67 |
* @warning When both sides of the JobQueue are in different threads (as it is usually the case), |
| 68 |
* make sure to capture all stack parameters of the job by value (i.e.: do not capture by |
| 69 |
* reference, parameters that live on the stack). |
| 70 |
*/ |
| 71 |
class JobQueue { |
| 72 |
public: |
| 73 |
using Job = std::function<void()>; |
| 74 |
|
| 75 |
JobQueue() = default; |
| 76 |
|
| 77 |
/** |
| 78 |
* Push a job to the back of the queue. |
| 79 |
* @param func anything that can be called |
| 80 |
* (e.g.: lambda, function or method with optional parameters) |
| 81 |
* @param args optional parameters to method or function. |
| 82 |
*/ |
| 83 |
template<typename CALLABLE, typename ... ARGS> |
| 84 |
void push(CALLABLE&& func, ARGS&&... args) { |
| 85 |
enqueue(Job(std::bind(std::forward<CALLABLE>(func), std::forward<ARGS>(args)...))); |
| 86 |
} |
| 87 |
|
| 88 |
/** |
| 89 |
* Checks whether the JobQueue is empty. |
| 90 |
* @return true if there is no jobs in the queue. |
| 91 |
*/ |
| 92 |
bool isEmpty() const; |
| 93 |
|
| 94 |
/** |
| 95 |
* Dequeues the oldest job and executes (runs) it. |
| 96 |
* @return true if a job was run. |
| 97 |
*/ |
| 98 |
bool runJobIfAny(); |
| 99 |
|
| 100 |
/** |
| 101 |
* Empties the queue and runs all jobs atomically w.r.t. the queue. Jobs are run in FIFO order. |
| 102 |
*/ |
| 103 |
void runAllJobs(); |
| 104 |
|
| 105 |
/** |
| 106 |
* Dequeues the oldest job. |
| 107 |
* @return a handle to the oldest job or null if the queue was empty. |
| 108 |
* @note the job can be manually run by calling job(). |
| 109 |
*/ |
| 110 |
Job pop(); |
| 111 |
|
| 112 |
private: |
| 113 |
JobQueue(const JobQueue& queue) = delete; |
| 114 |
JobQueue& operator=(const JobQueue& queue) = delete; |
| 115 |
|
| 116 |
void enqueue(Job&& job); |
| 117 |
|
| 118 |
std::deque<Job> m_queue; |
| 119 |
mutable std::mutex m_lock; |
| 120 |
}; |