A Progress indicator helper class. More...

#include <Progress.h>

Public Types
enum class	Origin : uint8_t { eInternal = 0 , eExternal = 1 }
	Enum to indicate the origin of a progress event, internal or external. More...

Public Member Functions
	Progress (std::string title, std::string details={}, std::optional< uint64_t > total=std::nullopt, lldb_private::Debugger *debugger=nullptr, Timeout< std::nano > minimum_report_time=std::nullopt, Origin origin=Origin::eInternal)
	Construct a progress object that will report information.
	~Progress ()
	Destroy the progress object.
void	Increment (uint64_t amount=1, std::optional< std::string > updated_detail={})
	Increment the progress and send a notification to the installed callback.

Static Public Attributes
static constexpr uint64_t	kNonDeterministicTotal = UINT64_MAX
	Used to indicate a non-deterministic progress report.
static constexpr std::chrono::milliseconds	kDefaultHighFrequencyReportTime
	The default report time for high frequency progress reports.

Private Member Functions
void	ReportProgress ()

Private Attributes
const uint64_t	m_total
	Total amount of work, use a std::nullopt in the constructor for non deterministic progress.
const Timeout< std::nano >	m_minimum_report_time
const std::string	m_title
	The title of the progress activity, also used as a category.
const uint64_t	m_progress_id
	A unique integer identifier for progress reporting.
const std::optional< lldb::user_id_t >	m_debugger_id
	The optional debugger ID to report progress to.
const Origin	m_origin
	The origin of the progress event, whether it is internal or external.
std::atomic< uint64_t >	m_completed = 0
	How much work ([0...m_total]) that has been completed.
std::atomic< uint64_t >	m_last_report_time_ns
	Time (in nanoseconds since epoch) of the last progress report.
std::mutex	m_mutex
	Guards non-const non-atomic members of the class.
std::string	m_details
	More specific information about the current file being displayed in the report.
std::optional< uint64_t >	m_prev_completed
	The "completed" value of the last reported event.

Static Private Attributes
static std::atomic< uint64_t >	g_id

Detailed Description

A Progress indicator helper class.

Any potentially long running sections of code in LLDB should report progress so that clients are aware of delays that might appear during debugging. Delays commonly include indexing debug information, parsing symbol tables for object files, downloading symbols from remote repositories, and many more things.

The Progress class helps make sure that progress is correctly reported and will always send an initial progress update, updates when Progress::Increment() is called, and also will make sure that a progress completed update is reported even if the user doesn't explicitly cause one to be sent.

The progress is reported via a callback whose type is ProgressCallback:

typedef void (*ProgressCallback)(uint64_t progress_id, const char *message, uint64_t completed, uint64_t total, void *baton);

This callback will always initially be called with completed set to zero and total set to the total amount specified in the constructor. This is considered the progress start event. As Progress::Increment() is called, the callback will be called as long as the Progress::m_completed has not yet exceeded the Progress::m_total. When the callback is called with Progress::m_completed == Progress::m_total, that is considered a progress completed event. If Progress::m_completed is non-zero and less than Progress::m_total, then this is considered a progress update event.

This callback will be called in the destructor if Progress::m_completed is not equal to Progress::m_total with the completed set to Progress::m_total. This ensures we always send a progress completed update even if the user does not.

Definition at line 60 of file Progress.h.

Member Enumeration Documentation

◆ Origin

enum class lldb_private::Progress::Origin : uint8_t

strong

Enum to indicate the origin of a progress event, internal or external.

Enumerator
eInternal
eExternal

Definition at line 63 of file Progress.h.

Constructor & Destructor Documentation

◆ Progress()

Progress::Progress	(	std::string	title,
		std::string	details = {},
		std::optional< uint64_t >	total = std::nullopt,
		lldb_private::Debugger *	debugger = nullptr,
		Timeout< std::nano >	minimum_report_time = std::nullopt,
		Progress::Origin	origin = Origin::eInternal )

Construct a progress object that will report information.

The constructor will create a unique progress reporting object and immediately send out a progress update by calling the installed callback with completed set to zero out of the specified total.

Parameters

[in]	title	The title of this progress activity.
[in]	details	Specific information about what the progress report is currently working on. Although not required, if the progress report is updated with Progress::Increment() then this field will be overwritten with the new set of details passed into that function, and the details passed initially will act as an "item 0" for the total set of items being reported on.
[in]	total	The total units of work to be done if specified, if set to std::nullopt then an indeterminate progress indicator should be displayed.
[in]	debugger	An optional debugger pointer to specify that this progress is to be reported only to specific debuggers.

Definition at line 28 of file Progress.cpp.

References g_id, g_progress_signposts, kNonDeterministicTotal, m_debugger_id, m_details, m_last_report_time_ns, m_minimum_report_time, m_mutex, m_origin, m_progress_id, m_title, m_total, Progress(), and ReportProgress().

Referenced by Progress().

◆ ~Progress()

Progress::~Progress ( )

Destroy the progress object.

If the progress has not yet sent a completion update, the destructor will send out a notification where the completed == m_total. This ensures that we always send out a progress complete notification.

Definition at line 51 of file Progress.cpp.

References g_progress_signposts, m_completed, m_mutex, m_title, m_total, and ReportProgress().

Member Function Documentation

◆ Increment()

void Progress::Increment	(	uint64_t	amount = 1,
		std::optional< std::string >	updated_detail = {} )

Increment the progress and send a notification to the installed callback.

If incrementing ends up exceeding m_total, m_completed will be updated to match m_total and no subsequent progress notifications will be sent. If no total was specified in the constructor, this function will not do anything nor send any progress updates.

Parameters

[in]	amount	The amount to increment m_completed by.
[in]	an	optional message associated with this update.

Definition at line 62 of file Progress.cpp.

References m_completed, m_details, m_last_report_time_ns, m_minimum_report_time, m_mutex, and ReportProgress().

Referenced by MinidumpFileBuilder::AddMemoryList_32(), MinidumpFileBuilder::AddMemoryList_64(), lldb_private::plugin::dwarf::SymbolFileDWARFDebugMap::ForEachSymbolFile(), lldb_private::plugin::dwarf::ManualDWARFIndex::Index(), and DynamicLoaderDarwinKernel::KextImageInfo::LoadImageUsingMemoryModule().

◆ ReportProgress()

void Progress::ReportProgress ( )

private

Definition at line 92 of file Progress.cpp.

References lldb::eBroadcastBitExternalProgress, lldb::eBroadcastBitProgress, eExternal, m_completed, m_debugger_id, m_details, m_origin, m_prev_completed, m_progress_id, m_title, m_total, and lldb_private::Debugger::ReportProgress().

Referenced by Increment(), Progress(), and ~Progress().

Member Data Documentation

◆ g_id

std::atomic< uint64_t > Progress::g_id

staticprivate

Definition at line 124 of file Progress.h.

Referenced by Progress().

◆ kDefaultHighFrequencyReportTime

std::chrono::milliseconds lldb_private::Progress::kDefaultHighFrequencyReportTime

staticconstexpr

Initial value:

=

std::chrono::milliseconds(20)

The default report time for high frequency progress reports.

Definition at line 119 of file Progress.h.

Referenced by lldb_private::plugin::dwarf::SymbolFileDWARFDebugMap::ForEachSymbolFile(), and lldb_private::plugin::dwarf::ManualDWARFIndex::Index().

◆ kNonDeterministicTotal

uint64_t lldb_private::Progress::kNonDeterministicTotal = UINT64_MAX

staticconstexpr

Used to indicate a non-deterministic progress report.

Definition at line 116 of file Progress.h.

Referenced by lldb_private::ProgressEventData::Dump(), lldb_private::ProgressEventData::IsFinite(), and Progress().

◆ m_completed

std::atomic<uint64_t> lldb_private::Progress::m_completed = 0

private

How much work ([0...m_total]) that has been completed.

Definition at line 147 of file Progress.h.

Referenced by Increment(), ReportProgress(), and ~Progress().

◆ m_debugger_id

const std::optional<lldb::user_id_t> lldb_private::Progress::m_debugger_id

private

The optional debugger ID to report progress to.

If this has no value then all debuggers will receive this event.

Definition at line 141 of file Progress.h.

Referenced by Progress(), and ReportProgress().

◆ m_details

std::string lldb_private::Progress::m_details

private

More specific information about the current file being displayed in the report.

Definition at line 157 of file Progress.h.

Referenced by Increment(), Progress(), and ReportProgress().

◆ m_last_report_time_ns

std::atomic<uint64_t> lldb_private::Progress::m_last_report_time_ns

private

Time (in nanoseconds since epoch) of the last progress report.

Definition at line 150 of file Progress.h.

Referenced by Increment(), and Progress().

◆ m_minimum_report_time

const Timeout<std::nano> lldb_private::Progress::m_minimum_report_time

private

Definition at line 131 of file Progress.h.

Referenced by Increment(), and Progress().

◆ m_mutex

std::mutex lldb_private::Progress::m_mutex

private

Guards non-const non-atomic members of the class.

Definition at line 153 of file Progress.h.

Referenced by Increment(), Progress(), and ~Progress().

◆ m_origin

const Origin lldb_private::Progress::m_origin

private

The origin of the progress event, whether it is internal or external.

Definition at line 144 of file Progress.h.

Referenced by Progress(), and ReportProgress().

◆ m_prev_completed

std::optional<uint64_t> lldb_private::Progress::m_prev_completed

private

The "completed" value of the last reported event.

Definition at line 160 of file Progress.h.

Referenced by ReportProgress().

◆ m_progress_id

const uint64_t lldb_private::Progress::m_progress_id

private

A unique integer identifier for progress reporting.

Definition at line 137 of file Progress.h.

Referenced by Progress(), and ReportProgress().

◆ m_title

const std::string lldb_private::Progress::m_title

private

The title of the progress activity, also used as a category.

Definition at line 134 of file Progress.h.

Referenced by Progress(), ReportProgress(), and ~Progress().

◆ m_total

const uint64_t lldb_private::Progress::m_total

private

Total amount of work, use a std::nullopt in the constructor for non deterministic progress.

Definition at line 128 of file Progress.h.

Referenced by Progress(), ReportProgress(), and ~Progress().

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

Public Types

Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Enumeration Documentation

◆ Origin

Constructor & Destructor Documentation

◆ Progress()

◆ ~Progress()

Member Function Documentation

◆ Increment()

◆ ReportProgress()

Member Data Documentation

◆ g_id

◆ kDefaultHighFrequencyReportTime

◆ kNonDeterministicTotal

◆ m_completed

◆ m_debugger_id

◆ m_details

◆ m_last_report_time_ns

◆ m_minimum_report_time

◆ m_mutex

◆ m_origin

◆ m_prev_completed

◆ m_progress_id

◆ m_title

◆ m_total