75 lines · plain
1%feature("docstring",2"A Progress indicator helper class.3 4Any potentially long running sections of code in LLDB should report5progress so that clients are aware of delays that might appear during6debugging. Delays commonly include indexing debug information, parsing7symbol tables for object files, downloading symbols from remote8repositories, and many more things.9 10The Progress class helps make sure that progress is correctly reported11and will always send an initial progress update, updates when12Progress::Increment() is called, and also will make sure that a progress13completed update is reported even if the user doesn't explicitly cause one14to be sent.15 16Progress can either be deterministic, incrementing up to a known total or non-deterministic17with an unbounded total. Deterministic is better if you know the items of work in advance, but non-deterministic18exposes a way to update a user during a long running process that work is taking place.19 20For all progresses the details provided in the constructor will be sent until an increment detail21is provided. This detail will also continue to be broadcasted on any subsequent update that doesn't22specify a new detail. Some implementations differ on throttling updates and this behavior differs primarily23if the progress is deterministic or non-deterministic. For DAP, non-deterministic update messages have a higher24throttling rate than deterministic ones.25 26Below are examples in Python for deterministic and non-deterministic progresses. ::27 28 deterministic_progress1 = lldb.SBProgress('Deterministic Progress', 'Detail', 3, lldb.SBDebugger) 29 for i in range(3): 30 deterministic_progress1.Increment(1, f'Update {i}') 31 # The call to Finalize() is a no-op as we already incremented the right amount of 32 # times and caused the end event to be sent. 33 deterministic_progress1.Finalize()34 35 deterministic_progress2 = lldb.SBProgress('Deterministic Progress', 'Detail', 10, lldb.SBDebugger) 36 for i in range(3): 37 deterministic_progress2.Increment(1, f'Update {i}') 38 # Cause the progress end event to be sent even if we didn't increment the right 39 # number of times. Real world examples would be in a try-finally block to ensure40 # progress clean-up.41 deterministic_progress2.Finalize() 42 43If you don't call Finalize() when the progress is not done, the progress object will eventually get44garbage collected by the Python runtime, the end event will eventually get sent, but it is best not to 45rely on the garbage collection when using lldb.SBProgress.46 47Non-deterministic progresses behave the same, but omit the total in the constructor. ::48 49 non_deterministic_progress = lldb.SBProgress('Non deterministic progress', 'Detail', lldb.SBDebugger)50 for i in range(10):51 non_deterministic_progress.Increment(1)52 # Explicitly send a progressEnd, otherwise this will be sent53 # when the python runtime cleans up this object.54 non_deterministic_progress.Finalize()55 56Additionally for Python, progress is supported in a with statement. ::57 with lldb.SBProgress('Non deterministic progress', 'Detail', lldb.SBDebugger) as progress:58 for i in range(10):59 progress.Increment(1)60 ...61 62The progress object is automatically finalized on the exit of the with block.63") lldb::SBProgress; 64 65%feature("docstring",66"Finalize the SBProgress, which will cause a progress end event to be emitted. This 67happens automatically when the SBProcess object is destroyed, but can be done explicitly 68with Finalize to avoid having to rely on the language semantics for destruction.69 70Note once finalized, no further increments will be processed.") lldb::SBProgress::Finalize;71 72%feature("docstring",73"Increment the progress by a given number of units, optionally with a message. Not all progress events are guaraunteed74to be sent, but incrementing to the total will always guarauntee a progress end event being sent.") lldb::SBProcess::Increment; 75