Add docs describing how the thread plan stack affects stepping #110167
Conversation
|
@llvm/pr-subscribers-lldb Author: None (jimingham) ChangesThis is a convenient little feature of lldb, but if you didn't know it was there you'd likely never discover it. Full diff: https://github.com/llvm/llvm-project/pull/110167.diff 1 Files Affected:
diff --git a/lldb/docs/use/tutorial.rst b/lldb/docs/use/tutorial.rst
index 00e7befdd087a4..57bf6c4479801e 100644
--- a/lldb/docs/use/tutorial.rst
+++ b/lldb/docs/use/tutorial.rst
@@ -536,6 +536,33 @@ This command will run the thread in the current frame until it reaches line 100
in this frame or stops if it leaves the current frame. This is a pretty close
equivalent to GDB's ``until`` command.
+One other useful thing to note about the lldb stepping commands is that they
+are implemented as a stack of interruptible operations. Until the operation -
+e.g. step to the next line - is completed, the operation will remain on the
+stack. If it is interrupted, new stepping commands will result in their
+operations being pushed onto the stack, each of them retired as they are completed.
+
+Suppose, for instance, you ``step-over`` a source line, and hit a breakpoint
+in a function called by the code of the line you are stepping over. Since the step-over
+operation remains on the stack, you can examine the state at
+the point of the breakpoint hit, step around in that frame, step in to other
+frames, hit other breakpoints, etc. Then when you are done, a simple ``continue``
+will resume the original ``step-over`` operation, only ending when the desired line is reached.
+This saves you from having to manually issue some number of ``step-out`` commands
+to get back to the frame you were stepping over.
+
+Hand-called functions using the ``expr`` command are also implemented by
+operations on this same stack. So if you are calling some code with the ``expr`` command,
+and hit a breakpoint during the evaluation of that code, you can examine
+the state where you stopped, step around at your convenience, and then issue a
+``continue`` which will finish the expression evaluation operation and print the function
+result.
+
+You can examine the state of the operations stack using the ``thread plan list``
+command, and if, for instance, you decide you don't actually want that outermost
+next to continue running, you can remove it with the ``thread plan discard``
+command.
+
A process, by default, will share the LLDB terminal with the inferior process.
When in this mode, much like when debugging with GDB, when the process is
running anything you type will go to the ``STDIN`` of the inferior process. To
|
|
Adding myself as a reviewer here, I didn't know about either of these commands and the behaviour described here is something I've noticed without knowing exactly what was happening 😅 . The explanation for the docs looks good here so this LGTM. |
lldb/docs/use/tutorial.rst
Outdated
| @@ -536,6 +536,33 @@ This command will run the thread in the current frame until it reaches line 100 | |||
| in this frame or stops if it leaves the current frame. This is a pretty close | |||
| equivalent to GDB's ``until`` command. | |||
|
|
|||
| One other useful thing to note about the lldb stepping commands is that they | |||
| are implemented as a stack of interruptible operations. Until the operation - | |||
| e.g. step to the next line - is completed, the operation will remain on the | |||
There was a problem hiding this comment.
Suggestion: Until the operation - ... - is completed, it will remain ...
You have the operation written multiple times here, I think it will flow better if you shorten that one.
There was a problem hiding this comment.
At the risk of releasing the bike-shedding kraken, I personally dislike some pronouns in technical docs. It's very easy to accidentally create ambiguity with pronouns, whereas repetition of the noun is always precise. Your suggestion is safe though
lldb/docs/use/tutorial.rst
Outdated
| One other useful thing to note about the lldb stepping commands is that they | ||
| are implemented as a stack of interruptible operations. Until the operation - | ||
| e.g. step to the next line - is completed, the operation will remain on the | ||
| stack. If it is interrupted, new stepping commands will result in their |
There was a problem hiding this comment.
I'm not 100% clear on what this sentence means. To confirm my understanding, you're trying to say something like "Interrupting a thread's execution doesn't clear the stack and running further stepping commands after that will push more operations to the stack". Is that right?
lldb/docs/use/tutorial.rst
Outdated
| operations being pushed onto the stack, each of them retired as they are completed. | ||
|
|
||
| Suppose, for instance, you ``step-over`` a source line, and hit a breakpoint | ||
| in a function called by the code of the line you are stepping over. Since the step-over |
There was a problem hiding this comment.
There's a lot of qualifiers in the second clause of the first sentence. I think you could rephrase it as something like this.
Suggestion:
Suppose, for instance, you `step-over` a source line with a function call. If there is a breakpoint placed in that function, LLDB will stop there with the `step-over` operation still on the stack.
| command, and if, for instance, you decide you don't actually want that outermost | ||
| next to continue running, you can remove it with the ``thread plan discard`` | ||
| command. | ||
|
|
There was a problem hiding this comment.
Suggestion: Perhaps mention the thread plan logging channel? thread plan list and thread plan discard are obviously more accessible but the logging channel shows the changes to the stack as they occur.
There was a problem hiding this comment.
Do you mean the step channel? There is a lot of detailed output there, I'm not sure we want the average tutorial.rst reader to be pointed that way...
There was a problem hiding this comment.
It's a fire-hose for sure, but OTOH, it's the only way to watch the machinery happen. It will be clear right away when you turn it on whether that info is for you or not...
lldb/docs/use/tutorial.rst
Outdated
| in a function called by the code of the line you are stepping over. Since the step-over | ||
| operation remains on the stack, you can examine the state at | ||
| the point of the breakpoint hit, step around in that frame, step in to other | ||
| frames, hit other breakpoints, etc. Then when you are done, a simple ``continue`` |
There was a problem hiding this comment.
Feel free to push back on this, but I think the big gap between the cause (1) and effect (2) here can be detrimental to the point you are trying to make:
- "Since the step-over operation remains on the stack..." and
- "when you are done, a simple
continuewill resume the original step-over...".
Maybe we could remove the "Since" clause (1) and fold it into 2? Something like:
You can examine [...]. When you are done, because the step-over operation remains on the stack, a simple
continue...
There was a problem hiding this comment.
I thought about that, but if I did it the other way I'm telling you about stepping around without really motivating it are related to what I was just discussing.
…110167) This is a convenient little feature of lldb, but if you didn't know it was there you'd likely never discover it.
This is a convenient little feature of lldb, but if you didn't know it was there you'd likely never discover it.