Recognition::Utility::ProgressTracker Class Reference

Thread-safe tracker for monitoring multi-step job progress. More...

#include <progress_tracker.hpp>

Public Member Functions
	ProgressTracker (std::uint64_t total_steps=1u) noexcept
	Construct a ProgressTracker with a given number of total steps.
void	Advance (std::uint64_t step_count=1u) noexcept
	Advance the progress by a number of completed steps.
std::uint64_t	GetCompletedSteps () const noexcept
	Get the number of completed steps.
Percentage	GetCompletionPercentage () const noexcept
	Get the completion percentage.
std::uint64_t	GetIncompletedSteps () const noexcept
	Get the number of remaining (incomplete) steps.
std::uint64_t	GetTotalSteps () const noexcept
	Get the total number of steps.
bool	IsCompleted () const noexcept
	Check if the job is complete.
void	MarkAsCompleted () noexcept
	Mark the job as fully completed.
void	Reset (std::uint64_t total_steps) noexcept
	Reset the tracker for a new job.
template<typename RepresentationT, typename PeriodT>
bool	TryWaitForCompletion (std::chrono::duration< RepresentationT, PeriodT > timeout) const
	Wait for completion with a timeout.
template<typename ClockT, typename DurationT>
bool	TryWaitForCompletionUntil (std::chrono::time_point< ClockT, DurationT > deadline) const
	Wait for completion until a deadline.
void	WaitForCompletion () const
	Wait indefinitely for the job to complete.

Private Attributes
std::mutex	m_mutex {}
std::condition_variable	m_condition_variable {}
std::uint64_t	m_total_steps
std::uint64_t	m_completed_steps {0u}

Detailed Description

Thread-safe tracker for monitoring multi-step job progress.

ProgressTracker provides a thread-safe mechanism for tracking the progress of jobs composed of multiple steps. It supports:

• Step counting: Track completed steps out of total steps
• Percentage calculation: Get completion as a percentage
• Waiting: Block until completion with optional timeouts
• Thread safety: All operations are protected by mutex

Thread Safety

All public methods are thread-safe. The typical pattern is:

• Worker thread: Calls Advance() after each step
• Monitor thread: Calls GetCompletionPercentage() or WaitForCompletion()

Example

using namespace std::chrono_literals;
 
ProgressTracker tracker{100};  // 100 steps total
 
// Worker updates progress
for (int i = 0; i < 100; ++i) {
    DoWork();
    tracker.Advance();
}
 
// Monitor checks progress
if (tracker.TryWaitForCompletion(5s)) {
    std::println("Completed!");
} else {
    std::println("Timed out at {}%",
        tracker.GetCompletionPercentage().Get());
}

See also

Percentage

SharedProgressTrackerT

MakeSharedProgressTracker()

Since

10.0.0

Constructor & Destructor Documentation

ProgressTracker()

Recognition::Utility::ProgressTracker::ProgressTracker ( std::uint64_t total_steps = 1u )

inlineexplicitnoexcept

Construct a ProgressTracker with a given number of total steps.

Parameters

[in]

total_steps

Total number of steps for the job (minimum 1). Defaults to 1 if not specified or if 0 is passed.

ProgressTracker tracker1;       // 1 step (for simple complete/not complete)
ProgressTracker tracker2{100};  // 100 steps

Since

10.0.0

Member Function Documentation

Advance()

void Recognition::Utility::ProgressTracker::Advance ( std::uint64_t step_count = 1u )

inlinenoexcept

Advance the progress by a number of completed steps.

Increments the completed step counter. The value is clamped to not exceed total_steps.

Parameters

[in]

step_count

Number of steps completed (default: 1).

Note

This method notifies any threads waiting on WaitForCompletion().

Thread-safe: protected by mutex.

tracker.Advance();      // Advance by 1
tracker.Advance(10);    // Advance by 10

Since

10.0.0

GetCompletedSteps()

std::uint64_t Recognition::Utility::ProgressTracker::GetCompletedSteps ( ) const

inlinenodiscardnoexcept

Get the number of completed steps.

Returns

Number of steps completed so far.

Note

Thread-safe: protected by mutex.

Since

10.0.0

GetCompletionPercentage()

Percentage Recognition::Utility::ProgressTracker::GetCompletionPercentage ( ) const

inlinenodiscardnoexcept

Get the completion percentage.

Returns

Percentage object representing completion (0% to 100%).

Note

Thread-safe: protected by mutex.

auto pct = tracker.GetCompletionPercentage();
std::println("Progress: {}", pct.ToString());  // e.g., "75%"

See also

Percentage

Since

10.0.0

GetIncompletedSteps()

std::uint64_t Recognition::Utility::ProgressTracker::GetIncompletedSteps ( ) const

inlinenodiscardnoexcept

Get the number of remaining (incomplete) steps.

Returns

Number of steps yet to be completed.

Note

Thread-safe: protected by mutex.

Since

10.0.0

GetTotalSteps()

std::uint64_t Recognition::Utility::ProgressTracker::GetTotalSteps ( ) const

inlinenodiscardnoexcept

Get the total number of steps.

Returns

Total number of steps for the job.

Note

Thread-safe: protected by mutex.

Since

10.0.0

IsCompleted()

bool Recognition::Utility::ProgressTracker::IsCompleted ( ) const

inlinenodiscardnoexcept

Check if the job is complete.

Returns

true if completed_steps >= total_steps, false otherwise.

Note

Thread-safe: protected by mutex.

Since

10.0.0

MarkAsCompleted()

void Recognition::Utility::ProgressTracker::MarkAsCompleted ( )

inlinenoexcept

Mark the job as fully completed.

Sets completed_steps to total_steps and notifies waiting threads.

Note

Thread-safe: protected by mutex.

// Early termination
if (shouldCancel) {
    tracker.MarkAsCompleted();
}

Since

10.0.0

Reset()

void Recognition::Utility::ProgressTracker::Reset ( std::uint64_t total_steps )

inlinenoexcept

Reset the tracker for a new job.

Resets completed_steps to 0 and optionally sets a new total.

Parameters

[in]

total_steps

New total number of steps (minimum 1).

Note

Thread-safe: protected by mutex.

tracker.Reset(200);  // Start new job with 200 steps

Since

10.0.0

TryWaitForCompletion()

template<typename RepresentationT, typename PeriodT>

bool Recognition::Utility::ProgressTracker::TryWaitForCompletion ( std::chrono::duration< RepresentationT, PeriodT > timeout ) const

inlinenodiscard

Wait for completion with a timeout.

Blocks the calling thread until the job completes or the timeout expires.

Template Parameters

RepresentationT	Duration representation type.
PeriodT	Duration period ratio type.

Parameters

[in]

timeout

Maximum duration to wait.

Returns

true if the job completed before the timeout, false if the timeout expired.

using namespace std::chrono_literals;
if (tracker.TryWaitForCompletion(5s)) {
    std::println("Job completed!");
} else {
    std::println("Timed out.");
}

Since

10.0.0

TryWaitForCompletionUntil()

template<typename ClockT, typename DurationT>

bool Recognition::Utility::ProgressTracker::TryWaitForCompletionUntil ( std::chrono::time_point< ClockT, DurationT > deadline ) const

inlinenodiscard

Wait for completion until a deadline.

Blocks the calling thread until the job completes or the deadline passes.

Template Parameters

ClockT	Clock type for the time point.
DurationT	Duration type for the time point.

Parameters

[in]

deadline

Absolute time point to wait until.

Returns

true if the job completed before the deadline, false if the deadline passed.

using namespace std::chrono_literals;
auto deadline = std::chrono::steady_clock::now() + 10s;
if (tracker.TryWaitForCompletionUntil(deadline)) {
    std::println("Completed on time!");
}

Since

10.0.0

WaitForCompletion()

void Recognition::Utility::ProgressTracker::WaitForCompletion ( ) const

inline

Wait indefinitely for the job to complete.

Blocks the calling thread until the job is fully completed.

Warning

This blocks forever if the job never completes. Consider using TryWaitForCompletion() with a timeout instead.

// Start background job
auto future = std::async([tracker] { return doWork(tracker); });
 
// Wait for completion (blocking)
tracker.WaitForCompletion();
auto result = future.get();

Since

10.0.0

Member Data Documentation

m_completed_steps

std::uint64_t Recognition::Utility::ProgressTracker::m_completed_steps {0u}

private

Steps completed so far.

m_condition_variable

std::condition_variable Recognition::Utility::ProgressTracker::m_condition_variable {}

mutableprivate

For wait operations.

m_mutex

std::mutex Recognition::Utility::ProgressTracker::m_mutex {}

mutableprivate

Mutex for thread-safe access.

m_total_steps

std::uint64_t Recognition::Utility::ProgressTracker::m_total_steps

private

Total steps in the job.

---

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

• progress_tracker.hpp