Debian Codegraph @

tools/cmgen/src/JobQueue.h

raw
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 };