|
LLDB mainline
|
A Progress indicator helper class. More...
#include <Progress.h>
Classes | |
| struct | ProgressData |
| Data belonging to this Progress event that is used for bookkeeping by ProgressManager. More... | |
Public Member Functions | |
| Progress (std::string title, std::string details={}, std::optional< uint64_t > total=std::nullopt, 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::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. | |
Private Member Functions | |
| void | ReportProgress () |
Private Attributes | |
| std::string | m_details |
| More specific information about the current file being displayed in the report. | |
| uint64_t | m_completed |
| How much work ([0...m_total]) that has been completed. | |
| uint64_t | m_total |
| Total amount of work, use a std::nullopt in the constructor for non deterministic progress. | |
| std::mutex | m_mutex |
| 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. | |
| ProgressData | m_progress_data |
| Data needed by the debugger to broadcast a progress event. | |
Static Private Attributes | |
| static std::atomic< uint64_t > | g_id |
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 59 of file Progress.h.
| Progress::Progress | ( | std::string | title, |
| std::string | details = {}, |
||
| std::optional< uint64_t > | total = std::nullopt, |
||
| 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.
| [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 23 of file Progress.cpp.
References lldb_private::Progress::ProgressData::debugger_id, lldb_private::ProgressManager::Enabled(), lldb_private::UserID::GetID(), lldb_private::ProgressManager::Increment(), lldb_private::ProgressManager::Instance(), m_mutex, m_progress_data, m_total, and ReportProgress().
| 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 44 of file Progress.cpp.
References lldb_private::ProgressManager::Decrement(), lldb_private::ProgressManager::Enabled(), lldb_private::ProgressManager::Instance(), m_completed, m_mutex, m_progress_data, m_total, and ReportProgress().
| 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.
| [in] | amount | The amount to increment m_completed by. |
| [in] | an | optional message associated with this update. |
Definition at line 56 of file Progress.cpp.
References m_completed, m_details, m_mutex, m_total, and ReportProgress().
Referenced by lldb_private::plugin::dwarf::ManualDWARFIndex::Index(), and DynamicLoaderDarwinKernel::KextImageInfo::LoadImageUsingMemoryModule().
|
private |
Definition at line 72 of file Progress.cpp.
References lldb_private::Progress::ProgressData::debugger_id, m_complete, m_completed, m_details, m_progress_data, m_total, lldb_private::Progress::ProgressData::progress_id, lldb_private::Debugger::ReportProgress(), and lldb_private::Progress::ProgressData::title.
Referenced by Increment(), Progress(), and ~Progress().
|
staticprivate |
Definition at line 123 of file Progress.h.
|
staticconstexpr |
Used to indicate a non-deterministic progress report.
Definition at line 107 of file Progress.h.
Referenced by lldb_private::ProgressEventData::Dump(), lldb_private::ProgressEventData::IsFinite(), and lldb_private::ProgressManager::ReportProgress().
|
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 136 of file Progress.h.
Referenced by ReportProgress().
|
private |
How much work ([0...m_total]) that has been completed.
Definition at line 128 of file Progress.h.
Referenced by Increment(), ReportProgress(), and ~Progress().
|
private |
More specific information about the current file being displayed in the report.
Definition at line 126 of file Progress.h.
Referenced by Increment(), and ReportProgress().
|
private |
Definition at line 132 of file Progress.h.
Referenced by Increment(), Progress(), and ~Progress().
|
private |
Data needed by the debugger to broadcast a progress event.
Definition at line 138 of file Progress.h.
Referenced by Progress(), ReportProgress(), and ~Progress().
|
private |
Total amount of work, use a std::nullopt in the constructor for non deterministic progress.
Definition at line 131 of file Progress.h.
Referenced by Increment(), Progress(), ReportProgress(), and ~Progress().
1.9.6