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
usher_cv_parallel::ThreadPoolBackend Class Referencefinal

Persistent std::thread pool implementing cv::parallel::ParallelForAPI. More...

#include <opencv_parallel.hpp>

Inheritance diagram for usher_cv_parallel::ThreadPoolBackend:
Collaboration diagram for usher_cv_parallel::ThreadPoolBackend:

Data Structures

struct  Worker
 Per-worker state owned until after its std::thread has joined. More...

Public Member Functions

 ThreadPoolBackend ()
 Construct an idle backend sized to the host's default CPU budget.
 ~ThreadPoolBackend () override
 Wait for any active region to finish, then stop and join all workers.
 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.
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.
int getThreadNum () const override
 Return the zero-based index of the calling thread within the pool.
int getNumThreads () const override
 Return the configured thread count for OpenCV parallel regions.
int setNumThreads (int nThreads) override
 Set the thread team size and immediately reclaim excess idle workers.
const char * getName () const override
 Return the backend identifier reported by cv::currentParallelFramework().
void enter_scope () noexcept
 Record entry into a ScopedBackend lifetime scope.
void leave_scope () noexcept
 Leave a ScopedBackend scope and join idle workers when the outermost scope exits.

Static Public Attributes

static constexpr int kMaxThreads = 256
 Upper bound on total OpenCV team size (calling thread plus workers).

Private Member Functions

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.
void join_extracted_workers (std::vector< std::unique_ptr< Worker > > &excess) noexcept
 Wake and join workers detached by extract_excess_workers_locked.
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.
void worker_loop (Worker *self) noexcept
 Persistent worker main loop awaiting new batch generations or retirement.

Static Private Member Functions

static int & tls_thread_num () noexcept
 Access the thread-local OpenCV worker index for the current thread.
static int default_threads () noexcept
 Determine the default thread count from OpenCV's CPU discovery.
static int normalize_threads (int requested) noexcept
 Normalize an OpenCV thread count argument into [1, kMaxThreads].

Private Attributes

std::mutex mutex_
std::condition_variable wake_cv_
std::condition_variable done_cv_
std::vector< std::unique_ptr< Worker > > workers_
int configured_threads_ = 1
std::atomic< int > atomic_threads_ {1}
size_t scope_depth_ = 0
bool busy_ = false
bool shutting_down_ = false
uint64_t generation_ = 0
size_t active_limit_ = 0
size_t pending_workers_ = 0
FN_parallel_for_body_cb_t current_body_ = nullptr
void * current_data_ = nullptr
int current_tasks_ = 0
int current_divisor_ = 1
std::atomic< int64_t > next_task_ {0}
std::atomic< bool > cancel_batch_ {false}
std::exception_ptr batch_exception_

Detailed Description

Persistent std::thread pool implementing cv::parallel::ParallelForAPI.

All batch state transitions (busy_, generation_, pending_workers_, worker resize/shutdown) occur under mutex_, while stripe indices within an active batch are claimed via next_task_ using guided chunk sizes matching OpenCV's stripe granularity. Nested or concurrent callers execute inline on the calling thread without blocking or oversubscribing workers.

Definition at line 63 of file opencv_parallel.hpp.

Constructor & Destructor Documentation

◆ ThreadPoolBackend() [1/2]

usher_cv_parallel::ThreadPoolBackend::ThreadPoolBackend ( )
inline

Construct an idle backend sized to the host's default CPU budget.

Definition at line 69 of file opencv_parallel.hpp.

◆ ~ThreadPoolBackend()

usher_cv_parallel::ThreadPoolBackend::~ThreadPoolBackend ( )
inlineoverride

Wait for any active region to finish, then stop and join all workers.

Definition at line 74 of file opencv_parallel.hpp.

◆ ThreadPoolBackend() [2/2]

usher_cv_parallel::ThreadPoolBackend::ThreadPoolBackend ( const ThreadPoolBackend & )
delete

Noncopyable: workers and synchronization state belong to one backend.

Member Function Documentation

◆ default_threads()

int usher_cv_parallel::ThreadPoolBackend::default_threads ( )
inlinestaticprivatenoexcept

Determine the default thread count from OpenCV's CPU discovery.

Returns
Clamped positive CPU count (1..kMaxThreads).

Definition at line 277 of file opencv_parallel.hpp.

◆ enter_scope()

void usher_cv_parallel::ThreadPoolBackend::enter_scope ( )
inlinenoexcept

Record entry into a ScopedBackend lifetime scope.

Definition at line 236 of file opencv_parallel.hpp.

◆ extract_excess_workers_locked()

std::vector< std::unique_ptr< Worker > > usher_cv_parallel::ThreadPoolBackend::extract_excess_workers_locked ( size_t keep)
inlineprivate

Mark workers at indices [keep, workers_.size()) for termination and detach them.

Parameters
[in]keepNumber of leading workers to retain in workers_.
Returns
Detached worker records whose threads must be joined after unlocking mutex_.

Definition at line 302 of file opencv_parallel.hpp.

◆ getName()

const char * usher_cv_parallel::ThreadPoolBackend::getName ( ) const
inlineoverride

Return the backend identifier reported by cv::currentParallelFramework().

Returns
Static backend name string.

Definition at line 233 of file opencv_parallel.hpp.

◆ getNumThreads()

int usher_cv_parallel::ThreadPoolBackend::getNumThreads ( ) const
inlineoverride

Return the configured thread count for OpenCV parallel regions.

Returns
Configured thread team size (>= 1).

Definition at line 203 of file opencv_parallel.hpp.

◆ getThreadNum()

int usher_cv_parallel::ThreadPoolBackend::getThreadNum ( ) const
inlineoverride

Return the zero-based index of the calling thread within the pool.

Returns
0 on the calling/external thread, or 1..N on pool workers.

Definition at line 197 of file opencv_parallel.hpp.

◆ join_extracted_workers()

void usher_cv_parallel::ThreadPoolBackend::join_extracted_workers ( std::vector< std::unique_ptr< Worker > > & excess)
inlineprivatenoexcept

Wake and join workers detached by extract_excess_workers_locked.

Parameters
[in,out]excessDetached worker list; cleared once all threads join.

Definition at line 320 of file opencv_parallel.hpp.

◆ leave_scope()

void usher_cv_parallel::ThreadPoolBackend::leave_scope ( )
inlinenoexcept

Leave a ScopedBackend scope and join idle workers when the outermost scope exits.

Definition at line 242 of file opencv_parallel.hpp.

◆ normalize_threads()

int usher_cv_parallel::ThreadPoolBackend::normalize_threads ( int requested)
inlinestaticprivatenoexcept

Normalize an OpenCV thread count argument into [1, kMaxThreads].

Parameters
[in]requestedThread count passed to setNumThreads.
Returns
Normalized positive team size.

Definition at line 287 of file opencv_parallel.hpp.

◆ operator=()

ThreadPoolBackend & usher_cv_parallel::ThreadPoolBackend::operator= ( const ThreadPoolBackend & )
delete

Nonassignable: replacing worker state would break active region ownership.

◆ parallel_for()

void usher_cv_parallel::ThreadPoolBackend::parallel_for ( int tasks,
FN_parallel_for_body_cb_t body_callback,
void * callback_data )
inlineoverride

Execute [0, tasks) across the configured thread team.

Parameters
[in]tasksNumber of stripes prepared by OpenCV's ProxyLoopBody.
[in]body_callbackOpenCV callback accepting a [start, end) subrange.
[in]callback_dataOpaque pointer forwarded to body_callback.

Definition at line 96 of file opencv_parallel.hpp.

◆ run_chunks()

void usher_cv_parallel::ThreadPoolBackend::run_chunks ( FN_parallel_for_body_cb_t body,
void * data,
int task_count,
int divisor )
inlineprivatenoexcept

Claim and execute guided [start, end) stripe chunks until exhausted.

Parameters
[in]bodyOpenCV stripe callback.
[in]dataOpaque callback context.
[in]task_countTotal stripes in the current batch.
[in]divisorGuided-scheduling divisor for the current team size.

Definition at line 340 of file opencv_parallel.hpp.

◆ setNumThreads()

int usher_cv_parallel::ThreadPoolBackend::setNumThreads ( int nThreads)
inlineoverride

Set the thread team size and immediately reclaim excess idle workers.

Parameters
[in]nThreadsRequested thread count (< 0 resets to default, 0/1 disables worker threads).
Returns
Previous configured thread count.

Definition at line 212 of file opencv_parallel.hpp.

◆ tls_thread_num()

int & usher_cv_parallel::ThreadPoolBackend::tls_thread_num ( )
inlinestaticprivatenoexcept

Access the thread-local OpenCV worker index for the current thread.

Returns
Reference to the calling thread's zero-based index (0 unless set by a pool worker).

Definition at line 268 of file opencv_parallel.hpp.

◆ worker_loop()

void usher_cv_parallel::ThreadPoolBackend::worker_loop ( Worker * self)
inlineprivatenoexcept

Persistent worker main loop awaiting new batch generations or retirement.

Parameters
[in]selfPointer to this worker's state record.

Definition at line 375 of file opencv_parallel.hpp.

Field Documentation

◆ active_limit_

size_t usher_cv_parallel::ThreadPoolBackend::active_limit_ = 0
private

Number of leading workers participating in generation_.

Definition at line 413 of file opencv_parallel.hpp.

◆ atomic_threads_

std::atomic<int> usher_cv_parallel::ThreadPoolBackend::atomic_threads_ {1}
private

Mirror of configured_threads_ for lock-free getNumThreads().

Definition at line 408 of file opencv_parallel.hpp.

◆ batch_exception_

std::exception_ptr usher_cv_parallel::ThreadPoolBackend::batch_exception_
private

First uncaught callback exception in the batch.

Definition at line 421 of file opencv_parallel.hpp.

◆ busy_

bool usher_cv_parallel::ThreadPoolBackend::busy_ = false
private

True while a parallel batch owns the worker team.

Definition at line 410 of file opencv_parallel.hpp.

◆ cancel_batch_

std::atomic<bool> usher_cv_parallel::ThreadPoolBackend::cancel_batch_ {false}
private

Set if a callback throws outside OpenCV's wrapper.

Definition at line 420 of file opencv_parallel.hpp.

◆ configured_threads_

int usher_cv_parallel::ThreadPoolBackend::configured_threads_ = 1
private

Configured team size under mutex_.

Definition at line 407 of file opencv_parallel.hpp.

◆ current_body_

FN_parallel_for_body_cb_t usher_cv_parallel::ThreadPoolBackend::current_body_ = nullptr
private

Active batch callback pointer.

Definition at line 415 of file opencv_parallel.hpp.

◆ current_data_

void* usher_cv_parallel::ThreadPoolBackend::current_data_ = nullptr
private

Active batch opaque callback data.

Definition at line 416 of file opencv_parallel.hpp.

◆ current_divisor_

int usher_cv_parallel::ThreadPoolBackend::current_divisor_ = 1
private

Active batch guided-scheduling divisor.

Definition at line 418 of file opencv_parallel.hpp.

◆ current_tasks_

int usher_cv_parallel::ThreadPoolBackend::current_tasks_ = 0
private

Active batch stripe count.

Definition at line 417 of file opencv_parallel.hpp.

◆ done_cv_

std::condition_variable usher_cv_parallel::ThreadPoolBackend::done_cv_
private

Signals batch completion (pending_workers_ == 0 / !busy_).

Definition at line 405 of file opencv_parallel.hpp.

◆ generation_

uint64_t usher_cv_parallel::ThreadPoolBackend::generation_ = 0
private

Monotonic batch identifier.

Definition at line 412 of file opencv_parallel.hpp.

◆ kMaxThreads

int usher_cv_parallel::ThreadPoolBackend::kMaxThreads = 256
staticconstexpr

Upper bound on total OpenCV team size (calling thread plus workers).

Definition at line 66 of file opencv_parallel.hpp.

◆ mutex_

std::mutex usher_cv_parallel::ThreadPoolBackend::mutex_
private

Guards pool membership and batch lifecycle.

Definition at line 403 of file opencv_parallel.hpp.

◆ next_task_

std::atomic<int64_t> usher_cv_parallel::ThreadPoolBackend::next_task_ {0}
private

Next unclaimed stripe index in [0, current_tasks_).

Definition at line 419 of file opencv_parallel.hpp.

◆ pending_workers_

size_t usher_cv_parallel::ThreadPoolBackend::pending_workers_ = 0
private

Participating workers not yet checked in for generation_.

Definition at line 414 of file opencv_parallel.hpp.

◆ scope_depth_

size_t usher_cv_parallel::ThreadPoolBackend::scope_depth_ = 0
private

Nesting count of active ScopedBackend guards.

Definition at line 409 of file opencv_parallel.hpp.

◆ shutting_down_

bool usher_cv_parallel::ThreadPoolBackend::shutting_down_ = false
private

Set during destruction to prevent further worker creation.

Definition at line 411 of file opencv_parallel.hpp.

◆ wake_cv_

std::condition_variable usher_cv_parallel::ThreadPoolBackend::wake_cv_
private

Signals workers on new batches or retirement.

Definition at line 404 of file opencv_parallel.hpp.

◆ workers_

std::vector<std::unique_ptr<Worker> > usher_cv_parallel::ThreadPoolBackend::workers_
private

Live persistent workers (0..configured_threads_-1).

Definition at line 406 of file opencv_parallel.hpp.


The documentation for this class was generated from the following file: