From 04700d5564a8b4acbaff8e21bc33db96b29b06e7 Mon Sep 17 00:00:00 2001 From: Enrico Granata Date: Wed, 16 Jan 2013 22:25:17 +0000 Subject: [PATCH] Changing the Python reference document to be more explicit in discouraging usage of lldb.{debugger,...} convenience variables for formatters and other non-interactive Python extensions llvm-svn: 172663 --- lldb/www/python-reference.html | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/lldb/www/python-reference.html b/lldb/www/python-reference.html index dface48..cad447b 100755 --- a/lldb/www/python-reference.html +++ b/lldb/www/python-reference.html @@ -96,15 +96,8 @@ Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.

This drops you into the embedded python interpreter. When running under the script command, lldb sets some convenience variables that give you quick access to the currently selected entities that characterize the program and debugger state. In each case, if there is no currently selected entity of the appropriate - type, the variable's IsValid method will return false. -

Note also, these variables hold the values - of the selected objects on entry to the embedded interpreter. They do not update as you use the LLDB - API's to change, for example, the currently selected stack frame or thread. -

As a corollary to this, because they get reset every time the script interpreter is entered, you should not - use these variables in general purpose python code that you write using the lldb module. After all, lldb can - run in a multithreaded environment, and another thread might call the "script" command, changing the value out - from under you.

- These are all global variables contained in the lldb python namespace :

+ type, the variable's IsValid method will return false. These variables are:

+ @@ -164,7 +157,7 @@ Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. 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> commmand can be used to change the + 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. @@ -181,14 +174,25 @@ Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. 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> commmand can be used to change the + 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
-

Once in the embedded interpreter, these objects can be used. To get started, note that almost +

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 on entry to the embedded interpreter. They do not update as you use the LLDB + API's to change, for example, the currently selected stack frame or thread. +

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 environment, and another thread might call the "script" command, changing the value out + from under you.

+ +

To get started with these objects and LLDB scripting, please note that almost all of the lldb Python objects are able to briefly describe themselves when you pass them to the Python print function: 

(lldb) script
-- 
2.7.4