LLDB mainline
Public Member Functions | Private Member Functions | Private Attributes | Static Private Attributes | List of all members
lldb_private::Progress Class Reference

A Progress indicator helper class. More...

#include <Progress.h>

Public Member Functions

 Progress (std::string title, uint64_t total=UINT64_MAX, lldb_private::Debugger *debugger=nullptr)
 Construct a progress object that will report information.
 
 ~Progress ()
 Destroy the progress object.
 
void Increment (uint64_t amount=1, std::string update={})
 Increment the progress and send a notification to the intalled callback.
 

Private Member Functions

void ReportProgress (std::string update={})
 

Private Attributes

std::string m_title
 The title of the progress activity.
 
std::mutex m_mutex
 
const uint64_t m_id
 A unique integer identifier for progress reporting.
 
uint64_t m_completed
 How much work ([0...m_total]) that has been completed.
 
const uint64_t m_total
 Total amount of work, UINT64_MAX for non deterministic progress.
 
std::optional< lldb::user_id_tm_debugger_id
 The optional debugger ID to report progress to.
 
bool m_complete = false
 Set to true when progress has been reported where m_completed == m_total to ensure that we don't send progress updates after progress has completed.
 

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 contructor. 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 56 of file Progress.h.

Constructor & Destructor Documentation

◆ Progress()

Progress::Progress ( std::string  title,
uint64_t  total = UINT64_MAX,
lldb_private::Debugger debugger = nullptr 
)

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]titleThe title of this progress activity.
[in]totalThe total units of work to be done if specified, if set to UINT64_MAX then an indeterminate progress indicator should be displayed.
[in]debuggerAn optional debugger pointer to specify that this progress is to be reported only to specific debuggers.

Definition at line 19 of file Progress.cpp.

References lldb_private::UserID::GetID(), m_debugger_id, m_mutex, and ReportProgress().

◆ ~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 29 of file Progress.cpp.

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

Member Function Documentation

◆ Increment()

void Progress::Increment ( uint64_t  amount = 1,
std::string  update = {} 
)

Increment the progress and send a notification to the intalled 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]amountThe amount to increment m_completed by.
[in]anoptional message associated with this update.

Definition at line 39 of file Progress.cpp.

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

Referenced by lldb_private::plugin::dwarf::ManualDWARFIndex::Index().

◆ ReportProgress()

void Progress::ReportProgress ( std::string  update = {})
private

Member Data Documentation

◆ g_id

std::atomic< uint64_t > Progress::g_id
staticprivate

Definition at line 96 of file Progress.h.

◆ m_complete

bool lldb_private::Progress::m_complete = false
private

Set to true when progress has been reported where m_completed == m_total to ensure that we don't send progress updates after progress has completed.

Definition at line 112 of file Progress.h.

Referenced by ReportProgress().

◆ m_completed

uint64_t lldb_private::Progress::m_completed
private

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

Definition at line 103 of file Progress.h.

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

◆ m_debugger_id

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 108 of file Progress.h.

Referenced by Progress(), and ReportProgress().

◆ m_id

const uint64_t lldb_private::Progress::m_id
private

A unique integer identifier for progress reporting.

Definition at line 101 of file Progress.h.

Referenced by ReportProgress().

◆ m_mutex

std::mutex lldb_private::Progress::m_mutex
private

Definition at line 99 of file Progress.h.

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

◆ m_title

std::string lldb_private::Progress::m_title
private

The title of the progress activity.

Definition at line 98 of file Progress.h.

Referenced by ReportProgress().

◆ m_total

const uint64_t lldb_private::Progress::m_total
private

Total amount of work, UINT64_MAX for non deterministic progress.

Definition at line 105 of file Progress.h.

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


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