1 //===-- Progress.h ----------------------------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 #ifndef LLDB_CORE_PROGRESS_H 10 #define LLDB_CORE_PROGRESS_H 11 12 #include "lldb/Utility/ConstString.h" 13 #include "lldb/lldb-types.h" 14 #include <atomic> 15 #include <mutex> 16 #include <optional> 17 18 namespace lldb_private { 19 20 /// A Progress indicator helper class. 21 /// 22 /// Any potentially long running sections of code in LLDB should report 23 /// progress so that clients are aware of delays that might appear during 24 /// debugging. Delays commonly include indexing debug information, parsing 25 /// symbol tables for object files, downloading symbols from remote 26 /// repositories, and many more things. 27 /// 28 /// The Progress class helps make sure that progress is correctly reported 29 /// and will always send an initial progress update, updates when 30 /// Progress::Increment() is called, and also will make sure that a progress 31 /// completed update is reported even if the user doesn't explicitly cause one 32 /// to be sent. 33 /// 34 /// The progress is reported via a callback whose type is ProgressCallback: 35 /// 36 /// typedef void (*ProgressCallback)(uint64_t progress_id, 37 /// const char *message, 38 /// uint64_t completed, 39 /// uint64_t total, 40 /// void *baton); 41 /// 42 /// This callback will always initially be called with "completed" set to zero 43 /// and "total" set to the total amount specified in the contructor. This is 44 /// considered the progress start event. As Progress::Increment() is called, 45 /// the callback will be called as long as the Progress::m_completed has not 46 /// yet exceeded the Progress::m_total. When the callback is called with 47 /// Progress::m_completed == Progress::m_total, that is considered a progress 48 /// completed event. If Progress::m_completed is non-zero and less than 49 /// Progress::m_total, then this is considered a progress update event. 50 /// 51 /// This callback will be called in the destructor if Progress::m_completed is 52 /// not equal to Progress::m_total with the "completed" set to 53 /// Progress::m_total. This ensures we always send a progress completed update 54 /// even if the user does not. 55 56 class Progress { 57 public: 58 /// Construct a progress object that will report information. 59 /// 60 /// The constructor will create a unique progress reporting object and 61 /// immediately send out a progress update by calling the installed callback 62 /// with completed set to zero out of the specified total. 63 /// 64 /// @param [in] title The title of this progress activity. 65 /// 66 /// @param [in] total The total units of work to be done if specified, if 67 /// set to UINT64_MAX then an indeterminate progress indicator should be 68 /// displayed. 69 /// 70 /// @param [in] debugger An optional debugger pointer to specify that this 71 /// progress is to be reported only to specific debuggers. 72 Progress(std::string title, uint64_t total = UINT64_MAX, 73 lldb_private::Debugger *debugger = nullptr); 74 75 /// Destroy the progress object. 76 /// 77 /// If the progress has not yet sent a completion update, the destructor 78 /// will send out a notification where the completed == m_total. This ensures 79 /// that we always send out a progress complete notification. 80 ~Progress(); 81 82 /// Increment the progress and send a notification to the intalled callback. 83 /// 84 /// If incrementing ends up exceeding m_total, m_completed will be updated 85 /// to match m_total and no subsequent progress notifications will be sent. 86 /// If no total was specified in the constructor, this function will not do 87 /// anything nor send any progress updates. 88 /// 89 /// @param [in] amount The amount to increment m_completed by. 90 void Increment(uint64_t amount = 1); 91 92 private: 93 void ReportProgress(); 94 static std::atomic<uint64_t> g_id; 95 /// The title of the progress activity. 96 std::string m_title; 97 std::mutex m_mutex; 98 /// A unique integer identifier for progress reporting. 99 const uint64_t m_id; 100 /// How much work ([0...m_total]) that has been completed. 101 uint64_t m_completed; 102 /// Total amount of work, UINT64_MAX for non deterministic progress. 103 const uint64_t m_total; 104 /// The optional debugger ID to report progress to. If this has no value then 105 /// all debuggers will receive this event. 106 std::optional<lldb::user_id_t> m_debugger_id; 107 /// Set to true when progress has been reported where m_completed == m_total 108 /// to ensure that we don't send progress updates after progress has 109 /// completed. 110 bool m_complete = false; 111 }; 112 113 } // namespace lldb_private 114 115 #endif // LLDB_CORE_PROGRESS_H 116