Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
opencv_parallel.hpp
Go to the documentation of this file.
1/*
2 * Copyright 2026 OpenUAS
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18/**
19 * @file opencv_parallel.hpp
20 * @brief Header-only C++17 `cv::parallel::ParallelForAPI` backend for Sensoraia.
21 * @details Replaces OpenCV's internal `pthreads` thread pool (`parallel_impl.cpp`,
22 * disabled at build time with `-DWITH_PTHREADS_PF=OFF`) so `ext/opencv` remains
23 * an unmodified upstream release tag while all multi-threaded `cv::parallel_for_`
24 * regions execute without lock-free data races under both GCC and Clang.
25 *
26 * Worker threads are created lazily on the first parallel region that needs more
27 * than one thread, parked on a condition variable between regions to avoid
28 * per-call thread-creation overhead, and joined deterministically when
29 * `cv::setNumThreads(1)` is requested or when the outermost `ScopedBackend`
30 * guard leaves `main()`.
31 */
32#ifndef USHER_OPENCV_PARALLEL_HPP
33#define USHER_OPENCV_PARALLEL_HPP
34
35#include <opencv2/core.hpp>
36#include <opencv2/core/parallel/parallel_backend.hpp>
37
38#include <algorithm>
39#include <atomic>
40#include <condition_variable>
41#include <cstddef>
42#include <cstdint>
43#include <exception>
44#include <memory>
45#include <mutex>
46#include <new>
47#include <system_error>
48#include <thread>
49#include <utility>
50#include <vector>
51
52/** @brief Deterministic, race-free `std::thread` backend for OpenCV parallel regions. */
54
55/**
56 * @brief Persistent `std::thread` pool implementing `cv::parallel::ParallelForAPI`.
57 * @details All batch state transitions (`busy_`, `generation_`, `pending_workers_`,
58 * worker resize/shutdown) occur under `mutex_`, while stripe indices within an
59 * active batch are claimed via `next_task_` using guided chunk sizes matching
60 * OpenCV's stripe granularity. Nested or concurrent callers execute inline on
61 * the calling thread without blocking or oversubscribing workers.
62 */
63class ThreadPoolBackend final : public cv::parallel::ParallelForAPI {
64 public:
65 /** @brief Upper bound on total OpenCV team size (calling thread plus workers). */
66 static constexpr int kMaxThreads = 256;
67
68 /** @brief Construct an idle backend sized to the host's default CPU budget. */
72
73 /** @brief Wait for any active region to finish, then stop and join all workers. */
74 ~ThreadPoolBackend() override {
75 std::vector<std::unique_ptr<Worker>> excess;
76 {
77 std::unique_lock<std::mutex> lock(mutex_);
78 done_cv_.wait(lock, [this] { return !busy_; });
79 shutting_down_ = true;
81 }
83 }
84
85 /** @brief Noncopyable: workers and synchronization state belong to one backend. */
87 /** @brief Nonassignable: replacing worker state would break active region ownership. */
89
90 /**
91 * @brief Execute `[0, tasks)` across the configured thread team.
92 * @param[in] tasks Number of stripes prepared by OpenCV's `ProxyLoopBody`.
93 * @param[in] body_callback OpenCV callback accepting a `[start, end)` subrange.
94 * @param[in] callback_data Opaque pointer forwarded to @p body_callback.
95 */
96 void parallel_for(int tasks,
97 FN_parallel_for_body_cb_t body_callback,
98 void* callback_data) override {
99 if (tasks <= 0 || body_callback == nullptr) {
100 return;
101 }
102 if (tasks == 1) {
103 body_callback(0, 1, callback_data);
104 return;
105 }
106
107 std::vector<std::unique_ptr<Worker>> pre_excess;
108 int divisor = 1;
109 {
110 std::unique_lock<std::mutex> lock(mutex_);
112 lock.unlock();
113 body_callback(0, tasks, callback_data);
114 return;
115 }
116
117 busy_ = true;
118 const size_t max_workers = static_cast<size_t>(configured_threads_ - 1);
119 pre_excess = extract_excess_workers_locked(max_workers);
120 const size_t needed_workers =
121 std::min(max_workers, static_cast<size_t>(tasks - 1));
122 while (workers_.size() < needed_workers) {
123 auto worker = std::make_unique<Worker>();
124 worker->slot_index = workers_.size();
125 worker->slot_id = static_cast<unsigned>(workers_.size() + 1);
126 worker->seen_generation = generation_;
127 try {
128 worker->thread =
129 std::thread(&ThreadPoolBackend::worker_loop, this, worker.get());
130 } catch (const std::system_error&) {
131 break;
132 } catch (const std::bad_alloc&) {
133 break;
134 }
135 workers_.push_back(std::move(worker));
136 }
137
138 if (workers_.empty()) {
139 busy_ = false;
140 done_cv_.notify_all();
141 lock.unlock();
142 join_extracted_workers(pre_excess);
143 body_callback(0, tasks, callback_data);
144 return;
145 }
146
147 const size_t active_workers = std::min(needed_workers, workers_.size());
148 const int team = static_cast<int>(active_workers + 1);
149 divisor = std::min(tasks, std::max(std::min(100, team * 4), team * 2));
150 current_body_ = body_callback;
151 current_data_ = callback_data;
152 current_tasks_ = tasks;
153 current_divisor_ = divisor;
154 next_task_.store(0, std::memory_order_relaxed);
155 cancel_batch_.store(false, std::memory_order_relaxed);
156 batch_exception_ = nullptr;
157 active_limit_ = active_workers;
158 pending_workers_ = active_workers;
159 ++generation_;
160 }
161
162 if (!pre_excess.empty()) {
163 join_extracted_workers(pre_excess);
164 } else {
165 wake_cv_.notify_all();
166 }
167
168 run_chunks(body_callback, callback_data, tasks, divisor);
169
170 std::vector<std::unique_ptr<Worker>> post_excess;
171 std::exception_ptr error;
172 {
173 std::unique_lock<std::mutex> lock(mutex_);
174 done_cv_.wait(lock, [this] { return pending_workers_ == 0; });
175 error = std::move(batch_exception_);
176 current_body_ = nullptr;
177 current_data_ = nullptr;
178 current_tasks_ = 0;
180 active_limit_ = 0;
181 post_excess = extract_excess_workers_locked(
182 static_cast<size_t>(configured_threads_ - 1));
183 busy_ = false;
184 done_cv_.notify_all();
185 }
186
187 join_extracted_workers(post_excess);
188 if (error) {
189 std::rethrow_exception(error);
190 }
191 }
192
193 /**
194 * @brief Return the zero-based index of the calling thread within the pool.
195 * @return `0` on the calling/external thread, or `1..N` on pool workers.
196 */
197 int getThreadNum() const override { return tls_thread_num(); }
198
199 /**
200 * @brief Return the configured thread count for OpenCV parallel regions.
201 * @return Configured thread team size (`>= 1`).
202 */
203 int getNumThreads() const override {
204 return atomic_threads_.load(std::memory_order_relaxed);
205 }
206
207 /**
208 * @brief Set the thread team size and immediately reclaim excess idle workers.
209 * @param[in] nThreads Requested thread count (`< 0` resets to default, `0`/`1` disables worker threads).
210 * @return Previous configured thread count.
211 */
212 int setNumThreads(int nThreads) override {
213 std::vector<std::unique_ptr<Worker>> excess;
214 int previous = 1;
215 {
216 std::lock_guard<std::mutex> lock(mutex_);
217 previous = configured_threads_;
219 atomic_threads_.store(configured_threads_, std::memory_order_relaxed);
220 if (!busy_) {
222 static_cast<size_t>(configured_threads_ - 1));
223 }
224 }
226 return previous;
227 }
228
229 /**
230 * @brief Return the backend identifier reported by `cv::currentParallelFramework()`.
231 * @return Static backend name string.
232 */
233 const char* getName() const override { return "sensoraia-std-thread"; }
234
235 /** @brief Record entry into a `ScopedBackend` lifetime scope. */
236 void enter_scope() noexcept {
237 std::lock_guard<std::mutex> lock(mutex_);
238 ++scope_depth_;
239 }
240
241 /** @brief Leave a `ScopedBackend` scope and join idle workers when the outermost scope exits. */
242 void leave_scope() noexcept {
243 std::vector<std::unique_ptr<Worker>> excess;
244 {
245 std::unique_lock<std::mutex> lock(mutex_);
246 if (scope_depth_ > 0 && --scope_depth_ == 0) {
247 done_cv_.wait(lock, [this] { return !busy_; });
249 }
250 }
252 }
253
254 private:
255 /** @brief Per-worker state owned until after its `std::thread` has joined. */
256 struct Worker {
257 std::thread thread; /**< OS thread running `worker_loop`. */
258 size_t slot_index = 0; /**< Zero-based index within `workers_`. */
259 unsigned slot_id = 1; /**< One-based thread index reported by `getThreadNum()`. */
260 uint64_t seen_generation = 0; /**< Last batch generation executed by this worker. */
261 bool stop = false; /**< Set under `mutex_` when retiring this worker. */
262 };
263
264 /**
265 * @brief Access the thread-local OpenCV worker index for the current thread.
266 * @return Reference to the calling thread's zero-based index (`0` unless set by a pool worker).
267 */
268 static int& tls_thread_num() noexcept {
269 thread_local int index = 0;
270 return index;
271 }
272
273 /**
274 * @brief Determine the default thread count from OpenCV's CPU discovery.
275 * @return Clamped positive CPU count (`1..kMaxThreads`).
276 */
277 static int default_threads() noexcept {
278 const int cpus = cv::getNumberOfCPUs();
279 return std::min(cpus > 0 ? cpus : 1, kMaxThreads);
280 }
281
282 /**
283 * @brief Normalize an OpenCV thread count argument into `[1, kMaxThreads]`.
284 * @param[in] requested Thread count passed to `setNumThreads`.
285 * @return Normalized positive team size.
286 */
287 static int normalize_threads(int requested) noexcept {
288 if (requested < 0) {
289 return default_threads();
290 }
291 if (requested <= 1) {
292 return 1;
293 }
294 return std::min(requested, kMaxThreads);
295 }
296
297 /**
298 * @brief Mark workers at indices `[keep, workers_.size())` for termination and detach them.
299 * @param[in] keep Number of leading workers to retain in `workers_`.
300 * @return Detached worker records whose threads must be joined after unlocking `mutex_`.
301 */
302 std::vector<std::unique_ptr<Worker>> extract_excess_workers_locked(size_t keep) {
303 std::vector<std::unique_ptr<Worker>> excess;
304 if (workers_.size() <= keep) {
305 return excess;
306 }
307 excess.reserve(workers_.size() - keep);
308 for (size_t index = keep; index < workers_.size(); ++index) {
309 workers_[index]->stop = true;
310 excess.push_back(std::move(workers_[index]));
311 }
312 workers_.resize(keep);
313 return excess;
314 }
315
316 /**
317 * @brief Wake and join workers detached by `extract_excess_workers_locked`.
318 * @param[in,out] excess Detached worker list; cleared once all threads join.
319 */
320 void join_extracted_workers(std::vector<std::unique_ptr<Worker>>& excess) noexcept {
321 if (excess.empty()) {
322 return;
323 }
324 wake_cv_.notify_all();
325 for (auto& worker : excess) {
326 if (worker && worker->thread.joinable()) {
327 worker->thread.join();
328 }
329 }
330 excess.clear();
331 }
332
333 /**
334 * @brief Claim and execute guided `[start, end)` stripe chunks until exhausted.
335 * @param[in] body OpenCV stripe callback.
336 * @param[in] data Opaque callback context.
337 * @param[in] task_count Total stripes in the current batch.
338 * @param[in] divisor Guided-scheduling divisor for the current team size.
339 */
340 void run_chunks(FN_parallel_for_body_cb_t body,
341 void* data,
342 int task_count,
343 int divisor) noexcept {
344 const int64_t total = static_cast<int64_t>(task_count);
345 const int64_t scale = static_cast<int64_t>(divisor > 0 ? divisor : 1);
346 while (!cancel_batch_.load(std::memory_order_relaxed)) {
347 const int64_t current = next_task_.load(std::memory_order_relaxed);
348 if (current >= total) {
349 break;
350 }
351 const int64_t remaining = total - current;
352 const int64_t chunk = std::max<int64_t>(1, remaining / scale);
353 const int64_t start = next_task_.fetch_add(chunk, std::memory_order_relaxed);
354 if (start >= total) {
355 break;
356 }
357 const int64_t end = std::min<int64_t>(total, start + chunk);
358 try {
359 body(static_cast<int>(start), static_cast<int>(end), data);
360 } catch (...) {
361 cancel_batch_.store(true, std::memory_order_relaxed);
362 std::lock_guard<std::mutex> lock(mutex_);
363 if (!batch_exception_) {
364 batch_exception_ = std::current_exception();
365 }
366 break;
367 }
368 }
369 }
370
371 /**
372 * @brief Persistent worker main loop awaiting new batch generations or retirement.
373 * @param[in] self Pointer to this worker's state record.
374 */
375 void worker_loop(Worker* self) noexcept {
376 tls_thread_num() = static_cast<int>(self->slot_id);
377 std::unique_lock<std::mutex> lock(mutex_);
378 for (;;) {
379 wake_cv_.wait(lock, [this, self] {
380 return self->stop ||
381 (busy_ && self->slot_index < active_limit_ &&
382 self->seen_generation != generation_);
383 });
384 if (self->stop) {
385 return;
386 }
387 self->seen_generation = generation_;
388 const FN_parallel_for_body_cb_t body = current_body_;
389 void* const data = current_data_;
390 const int task_count = current_tasks_;
391 const int divisor = current_divisor_;
392 lock.unlock();
393
394 run_chunks(body, data, task_count, divisor);
395
396 lock.lock();
397 if (--pending_workers_ == 0) {
398 done_cv_.notify_all();
399 }
400 }
401 }
402
403 std::mutex mutex_; /**< Guards pool membership and batch lifecycle. */
404 std::condition_variable wake_cv_; /**< Signals workers on new batches or retirement. */
405 std::condition_variable done_cv_; /**< Signals batch completion (`pending_workers_ == 0` / `!busy_`). */
406 std::vector<std::unique_ptr<Worker>> workers_; /**< Live persistent workers (`0..configured_threads_-1`). */
407 int configured_threads_ = 1; /**< Configured team size under `mutex_`. */
408 std::atomic<int> atomic_threads_{1}; /**< Mirror of `configured_threads_` for lock-free `getNumThreads()`. */
409 size_t scope_depth_ = 0; /**< Nesting count of active `ScopedBackend` guards. */
410 bool busy_ = false; /**< True while a parallel batch owns the worker team. */
411 bool shutting_down_ = false; /**< Set during destruction to prevent further worker creation. */
412 uint64_t generation_ = 0; /**< Monotonic batch identifier. */
413 size_t active_limit_ = 0; /**< Number of leading workers participating in `generation_`. */
414 size_t pending_workers_ = 0; /**< Participating workers not yet checked in for `generation_`. */
415 FN_parallel_for_body_cb_t current_body_ = nullptr;/**< Active batch callback pointer. */
416 void* current_data_ = nullptr; /**< Active batch opaque callback data. */
417 int current_tasks_ = 0; /**< Active batch stripe count. */
418 int current_divisor_ = 1; /**< Active batch guided-scheduling divisor. */
419 std::atomic<int64_t> next_task_{0}; /**< Next unclaimed stripe index in `[0, current_tasks_)`. */
420 std::atomic<bool> cancel_batch_{false}; /**< Set if a callback throws outside OpenCV's wrapper. */
421 std::exception_ptr batch_exception_; /**< First uncaught callback exception in the batch. */
422};
423
424/**
425 * @brief Install the process-wide Sensoraia OpenCV parallel backend once.
426 * @return Shared handle to the installed `ThreadPoolBackend` instance.
427 */
428inline const std::shared_ptr<ThreadPoolBackend>& ensure_installed() {
429 static const std::shared_ptr<ThreadPoolBackend> backend = [] {
430 auto instance = std::make_shared<ThreadPoolBackend>();
431 cv::parallel::setParallelForBackend(instance, true);
432 return instance;
433 }();
434 return backend;
435}
436
437/**
438 * @brief RAII guard installing the backend at startup and joining workers before `main()` exits.
439 * @details Avoids leaving worker threads alive into static storage teardown in
440 * `-static` executables while still allowing unit tests without `main()` to
441 * call `ensure_installed()` directly.
442 */
444 public:
445 /** @brief Ensure the OpenCV parallel backend is registered and enter a lifetime scope. */
447
448 /** @brief Exit the scope and join idle worker threads when the outermost guard ends. */
449 ~ScopedBackend() { backend_->leave_scope(); }
450
451 /** @brief Noncopyable: each guard must pair one scope entry with one exit. */
452 ScopedBackend(const ScopedBackend&) = delete;
453 /** @brief Nonassignable: a guard cannot transfer an active scope. */
455
456 private:
457 std::shared_ptr<ThreadPoolBackend> backend_; /**< Retained backend instance for symmetric scope exit. */
458};
459
460} // namespace usher_cv_parallel
461
462#endif // USHER_OPENCV_PARALLEL_HPP
std::shared_ptr< ThreadPoolBackend > backend_
~ScopedBackend()
Exit the scope and join idle worker threads when the outermost guard ends.
ScopedBackend(const ScopedBackend &)=delete
Noncopyable: each guard must pair one scope entry with one exit.
ScopedBackend & operator=(const ScopedBackend &)=delete
Nonassignable: a guard cannot transfer an active scope.
ScopedBackend()
Ensure the OpenCV parallel backend is registered and enter a lifetime scope.
static int & tls_thread_num() noexcept
Access the thread-local OpenCV worker index for the current thread.
void run_chunks(FN_parallel_for_body_cb_t body, void *data, int task_count, int divisor) noexcept
Claim and execute guided [start, end) stripe chunks until exhausted.
int getThreadNum() const override
Return the zero-based index of the calling thread within the pool.
FN_parallel_for_body_cb_t current_body_
int setNumThreads(int nThreads) override
Set the thread team size and immediately reclaim excess idle workers.
void leave_scope() noexcept
Leave a ScopedBackend scope and join idle workers when the outermost scope exits.
std::vector< std::unique_ptr< Worker > > workers_
void join_extracted_workers(std::vector< std::unique_ptr< Worker > > &excess) noexcept
Wake and join workers detached by extract_excess_workers_locked.
std::vector< std::unique_ptr< Worker > > extract_excess_workers_locked(size_t keep)
Mark workers at indices [keep, workers_.size()) for termination and detach them.
~ThreadPoolBackend() override
Wait for any active region to finish, then stop and join all workers.
ThreadPoolBackend()
Construct an idle backend sized to the host's default CPU budget.
ThreadPoolBackend(const ThreadPoolBackend &)=delete
Noncopyable: workers and synchronization state belong to one backend.
ThreadPoolBackend & operator=(const ThreadPoolBackend &)=delete
Nonassignable: replacing worker state would break active region ownership.
const char * getName() const override
Return the backend identifier reported by cv::currentParallelFramework().
int getNumThreads() const override
Return the configured thread count for OpenCV parallel regions.
static int default_threads() noexcept
Determine the default thread count from OpenCV's CPU discovery.
void parallel_for(int tasks, FN_parallel_for_body_cb_t body_callback, void *callback_data) override
Execute [0, tasks) across the configured thread team.
static constexpr int kMaxThreads
Upper bound on total OpenCV team size (calling thread plus workers).
static int normalize_threads(int requested) noexcept
Normalize an OpenCV thread count argument into [1, kMaxThreads].
void worker_loop(Worker *self) noexcept
Persistent worker main loop awaiting new batch generations or retirement.
void enter_scope() noexcept
Record entry into a ScopedBackend lifetime scope.
static bool start(uint32_t session)
Admit a nonzero session and discard correlation from the previous one.
struct jpeg_error_mgr error
Definition lwir_image.c:60
Deterministic, race-free std::thread backend for OpenCV parallel regions.
const std::shared_ptr< ThreadPoolBackend > & ensure_installed()
Install the process-wide Sensoraia OpenCV parallel backend once.
Per-worker state owned until after its std::thread has joined.