JDevlieghere created this revision. JDevlieghere added a reviewer: LLDB. JDevlieghere requested review of this revision.
Add a column to the table of convenience variables with the equivalent API to get to the current debugger, target, process, etc. We often get asked to make convenience variables available outside of the interactive interpreter. After explaining why that's not possible, a common complaint is that it's hard to find out how to get to these variables in a non-interactive context, for example how to get to the current frame when given a thread.. This patch aims to alleviate that by including the APIs to navigate between these instances in the table. https://reviews.llvm.org/D97778 Files: lldb/docs/use/python-reference.rst Index: lldb/docs/use/python-reference.rst =================================================================== --- lldb/docs/use/python-reference.rst +++ lldb/docs/use/python-reference.rst @@ -98,39 +98,38 @@ appropriate type, the variable's IsValid method will return false. These variables are: -+-------------------+---------------------+-------------------------------------------------------------------------------------+ -| Variable | Type | Description | -+-------------------+---------------------+-------------------------------------------------------------------------------------+ -| **lldb.debugger** | **lldb.SBDebugger** | Contains the debugger object whose **script** command was invoked. | -| | | The **lldb.SBDebugger** object owns the command interpreter | -| | | and all the targets in your debug session. There will always be a | -| | | Debugger in the embedded interpreter. | -+-------------------+---------------------+-------------------------------------------------------------------------------------+ -| **lldb.target** | **lldb.SBTarget** | Contains the currently selected target - for instance the one made with the | -| | | **file** or selected by the **target select <target-index>** command. | -| | | The **lldb.SBTarget** manages one running process, and all the executable | -| | | and debug files for the process. | -+-------------------+---------------------+-------------------------------------------------------------------------------------+ -| **lldb.process** | **lldb.SBProcess** | Contains the process of the currently selected target. | -| | | The **lldb.SBProcess** object manages the threads and allows access to | -| | | memory for the process. | -+-------------------+---------------------+-------------------------------------------------------------------------------------+ -| **lldb.thread** | **lldb.SBThread** | Contains the currently selected thread. | -| | | The **lldb.SBThread** object manages the stack frames in that thread. | -| | | A thread is always selected in the command interpreter when a target stops. | -| | | The **thread select <thread-index>** command can be used to change the | -| | | currently selected thread. So as long as you have a stopped process, there will be | -| | | some selected thread. | -+-------------------+---------------------+-------------------------------------------------------------------------------------+ -| **lldb.frame** | **lldb.SBFrame** | Contains the currently selected stack frame. | -| | | The **lldb.SBFrame** object manage the stack locals and the register set for | -| | | that stack. | -| | | A stack frame is always selected in the command interpreter when a target stops. | -| | | The **frame select <frame-index>** command can be used to change the | -| | | currently selected frame. So as long as you have a stopped process, there will | -| | | be some selected frame. | -+-------------------+---------------------+-------------------------------------------------------------------------------------+ - ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| Variable | Type | Equivalent | Description | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| **lldb.debugger** | **lldb.SBDebugger** | **SBTarget.GetDebugger()** | Contains the debugger object whose **script** command was invoked. | +| | | | The **lldb.SBDebugger** object owns the command interpreter | +| | | | and all the targets in your debug session. There will always be a | +| | | | Debugger in the embedded interpreter. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| **lldb.target** | **lldb.SBTarget** | **SBDebugger.GetSelectedTarget()** | Contains the currently selected target - for instance the one made with the | +| | | **SBProcess.GetTarget()** | **file** or selected by the **target select <target-index>** command. | +| | | | The **lldb.SBTarget** manages one running process, and all the executable | +| | | | and debug files for the process. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| **lldb.process** | **lldb.SBProcess** | **SBTarget.GetProcess()** | Contains the process of the currently selected target. | +| | | **SBThread.GetProcess()** | The **lldb.SBProcess** object manages the threads and allows access to | +| | | | memory for the process. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| **lldb.thread** | **lldb.SBThread** | **SBProcess.GetSelectedThread()** | Contains the currently selected thread. | +| | | **SBFrame.GetThread()** | The **lldb.SBThread** object manages the stack frames in that thread. | +| | | | A thread is always selected in the command interpreter when a target stops. | +| | | | The **thread select <thread-index>** command can be used to change the | +| | | | currently selected thread. So as long as you have a stopped process, there will be | +| | | | some selected thread. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| **lldb.frame** | **lldb.SBFrame** | **SBThread.GetSelectedFrame()** | Contains the currently selected stack frame. | +| | | | The **lldb.SBFrame** object manage the stack locals and the register set for | +| | | | that stack. | +| | | | A stack frame is always selected in the command interpreter when a target stops. | +| | | | The **frame select <frame-index>** command can be used to change the | +| | | | currently selected frame. So as long as you have a stopped process, there will | +| | | | be some selected frame. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ While extremely convenient, these variables have a couple caveats that you should be aware of. First of all, they hold the values of the selected objects @@ -140,8 +139,12 @@ Moreover, they are only defined and meaningful while in the interactive Python interpreter. There is no guarantee on their value in any other situation, hence you should not use them when defining Python formatters, breakpoint scripts and -commands (or any other Python extension point that LLDB provides). As a -rationale for such behavior, consider that lldb can run in a multithreaded +commands (or any other Python extension point that LLDB provides). For the +latter you'll be passed a an SBDebugger, SBTarget, SBProcess, SBThread or +SBframe instance and you can use the functions from the "Equivalent" column to +navigate between them. + +As a rationale for such behavior, consider that lldb can run in a multithreaded environment, and another thread might call the "script" command, changing the value out from under you.
Index: lldb/docs/use/python-reference.rst =================================================================== --- lldb/docs/use/python-reference.rst +++ lldb/docs/use/python-reference.rst @@ -98,39 +98,38 @@ appropriate type, the variable's IsValid method will return false. These variables are: -+-------------------+---------------------+-------------------------------------------------------------------------------------+ -| Variable | Type | Description | -+-------------------+---------------------+-------------------------------------------------------------------------------------+ -| **lldb.debugger** | **lldb.SBDebugger** | Contains the debugger object whose **script** command was invoked. | -| | | The **lldb.SBDebugger** object owns the command interpreter | -| | | and all the targets in your debug session. There will always be a | -| | | Debugger in the embedded interpreter. | -+-------------------+---------------------+-------------------------------------------------------------------------------------+ -| **lldb.target** | **lldb.SBTarget** | Contains the currently selected target - for instance the one made with the | -| | | **file** or selected by the **target select <target-index>** command. | -| | | The **lldb.SBTarget** manages one running process, and all the executable | -| | | and debug files for the process. | -+-------------------+---------------------+-------------------------------------------------------------------------------------+ -| **lldb.process** | **lldb.SBProcess** | Contains the process of the currently selected target. | -| | | The **lldb.SBProcess** object manages the threads and allows access to | -| | | memory for the process. | -+-------------------+---------------------+-------------------------------------------------------------------------------------+ -| **lldb.thread** | **lldb.SBThread** | Contains the currently selected thread. | -| | | The **lldb.SBThread** object manages the stack frames in that thread. | -| | | A thread is always selected in the command interpreter when a target stops. | -| | | The **thread select <thread-index>** command can be used to change the | -| | | currently selected thread. So as long as you have a stopped process, there will be | -| | | some selected thread. | -+-------------------+---------------------+-------------------------------------------------------------------------------------+ -| **lldb.frame** | **lldb.SBFrame** | Contains the currently selected stack frame. | -| | | The **lldb.SBFrame** object manage the stack locals and the register set for | -| | | that stack. | -| | | A stack frame is always selected in the command interpreter when a target stops. | -| | | The **frame select <frame-index>** command can be used to change the | -| | | currently selected frame. So as long as you have a stopped process, there will | -| | | be some selected frame. | -+-------------------+---------------------+-------------------------------------------------------------------------------------+ - ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| Variable | Type | Equivalent | Description | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| **lldb.debugger** | **lldb.SBDebugger** | **SBTarget.GetDebugger()** | Contains the debugger object whose **script** command was invoked. | +| | | | The **lldb.SBDebugger** object owns the command interpreter | +| | | | and all the targets in your debug session. There will always be a | +| | | | Debugger in the embedded interpreter. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| **lldb.target** | **lldb.SBTarget** | **SBDebugger.GetSelectedTarget()** | Contains the currently selected target - for instance the one made with the | +| | | **SBProcess.GetTarget()** | **file** or selected by the **target select <target-index>** command. | +| | | | The **lldb.SBTarget** manages one running process, and all the executable | +| | | | and debug files for the process. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| **lldb.process** | **lldb.SBProcess** | **SBTarget.GetProcess()** | Contains the process of the currently selected target. | +| | | **SBThread.GetProcess()** | The **lldb.SBProcess** object manages the threads and allows access to | +| | | | memory for the process. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| **lldb.thread** | **lldb.SBThread** | **SBProcess.GetSelectedThread()** | Contains the currently selected thread. | +| | | **SBFrame.GetThread()** | The **lldb.SBThread** object manages the stack frames in that thread. | +| | | | A thread is always selected in the command interpreter when a target stops. | +| | | | The **thread select <thread-index>** command can be used to change the | +| | | | currently selected thread. So as long as you have a stopped process, there will be | +| | | | some selected thread. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| **lldb.frame** | **lldb.SBFrame** | **SBThread.GetSelectedFrame()** | Contains the currently selected stack frame. | +| | | | The **lldb.SBFrame** object manage the stack locals and the register set for | +| | | | that stack. | +| | | | A stack frame is always selected in the command interpreter when a target stops. | +| | | | The **frame select <frame-index>** command can be used to change the | +| | | | currently selected frame. So as long as you have a stopped process, there will | +| | | | be some selected frame. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ While extremely convenient, these variables have a couple caveats that you should be aware of. First of all, they hold the values of the selected objects @@ -140,8 +139,12 @@ Moreover, they are only defined and meaningful while in the interactive Python interpreter. There is no guarantee on their value in any other situation, hence you should not use them when defining Python formatters, breakpoint scripts and -commands (or any other Python extension point that LLDB provides). As a -rationale for such behavior, consider that lldb can run in a multithreaded +commands (or any other Python extension point that LLDB provides). For the +latter you'll be passed a an SBDebugger, SBTarget, SBProcess, SBThread or +SBframe instance and you can use the functions from the "Equivalent" column to +navigate between them. + +As a rationale for such behavior, consider that lldb can run in a multithreaded environment, and another thread might call the "script" command, changing the value out from under you.
_______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
