[Lldb-commits] [PATCH] D96368: Document the "extra_args" parameter to scripted breakpoint callbacks

[Jim Ingham via Phabricator via lldb-commits]

This revision was landed with ongoing or failed builds.
This revision was automatically updated to reflect the committed changes.
Closed by commit rG365b186c242b: Add documentation for the extra_args parameter to breakpoint commands. (authored by jingham).

Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D96368/new/

https://reviews.llvm.org/D96368

Files:
  lldb/docs/use/python-reference.rst
  lldb/source/Commands/CommandObjectBreakpointCommand.cpp


Index: lldb/source/Commands/CommandObjectBreakpointCommand.cpp
===================================================================
--- lldb/source/Commands/CommandObjectBreakpointCommand.cpp
+++ lldb/source/Commands/CommandObjectBreakpointCommand.cpp
@@ -117,14 +117,22 @@
 
     --python-function myutils.breakpoint_callback
 
-The function itself must have the following prototype:
+The function itself must have either of the following prototypes:
 
 def breakpoint_callback(frame, bp_loc, dict):
   # Your code goes here
 
+or:
+
+def breakpoint_callback(frame, bp_loc, extra_args, dict):
+  # Your code goes here
+
 )"
         "The arguments are the same as the arguments passed to generated functions as \
-described above.  Note that the global variable 'lldb.frame' will NOT be updated when \
+described above.  In the second form, any -k and -v pairs provided to the command will \ 
+be packaged into a SBDictionary in an SBStructuredData and passed as the extra_args parameter. \
+\n\n\  
+Note that the global variable 'lldb.frame' will NOT be updated when \
 this function is called, so be sure to use the 'frame' argument. The 'frame' argument \
 can get you to the thread via frame.GetThread(), the thread can get you to the \
 process via thread.GetProcess(), and the process can get you back to the target \
Index: lldb/docs/use/python-reference.rst
===================================================================
--- lldb/docs/use/python-reference.rst
+++ lldb/docs/use/python-reference.rst
@@ -182,20 +182,32 @@
   def breakpoint_function_wrapper(frame, bp_loc, dict):
      # Your code goes here
 
+or:
 
-+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
-| Argument   | Type                          | Description                                                                                                                               |
-+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
-| **frame**  | **lldb.SBFrame**              | The current stack frame where the breakpoint got hit.                                                                                     |
-|            |                               | The object will always be valid.                                                                                                          |
-|            |                               | This **frame** argument might *not* match the currently selected stack frame found in the **lldb** module global variable **lldb.frame**. |
-+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
-| **bp_loc** | **lldb.SBBreakpointLocation** | The breakpoint location that just got hit. Breakpoints are represented by **lldb.SBBreakpoint**                                           |
-|            |                               | objects. These breakpoint objects can have one or more locations. These locations                                                         |
-|            |                               | are represented by **lldb.SBBreakpointLocation** objects.                                                                                 |
-+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
-| **dict**   | **dict**                      | The python session dictionary as a standard python dictionary object.                                                                     |
-+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+::
+
+  def breakpoint_function_wrapper(frame, bp_loc, extra_args, dict):
+     # Your code goes here
+
+
++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+| Argument       | Type                          | Description                                                                                                                               |
++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+| **frame**      | **lldb.SBFrame**              | The current stack frame where the breakpoint got hit.                                                                                     |
+|                |                               | The object will always be valid.                                                                                                          |
+|                |                               | This **frame** argument might *not* match the currently selected stack frame found in the **lldb** module global variable **lldb.frame**. |
++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+| **bp_loc**     | **lldb.SBBreakpointLocation** | The breakpoint location that just got hit. Breakpoints are represented by **lldb.SBBreakpoint**                                           |
+|                |                               | objects. These breakpoint objects can have one or more locations. These locations                                                         |
+|                |                               | are represented by **lldb.SBBreakpointLocation** objects.                                                                                 |
++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+| **extra_args** | **lldb.SBStructuredData**     | **Optional** If your breakpoint callback function takes this extra parameter, then when the callback gets added to a breakpoint, its      |
+|                |                               | contents can parametrize this use of the callback.  For instance, instead of writing a callback that stops when the caller is "Foo",      |
+|                |                               | you could take the function name from a field in the **extra_args**, making the callback more general.  The **-k** and **-v** options     |
+|                |                               | to **breakpoint command add** will be passed as a Dictionary in the **extra_args** parameter, or you can provide it with the SB API's.    |
++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+| **dict**       | **dict**                      | The python session dictionary as a standard python dictionary object.                                                                     |
++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
 
 Optionally, a Python breakpoint command can return a value. Returning False
 tells LLDB that you do not want to stop at the breakpoint. Any other return


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D96368.322523.patch
Type: text/x-patch
Size: 7792 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/lldb-commits/attachments/20210209/a3d35178/attachment.bin>