Add the ability to write 'target stop-hooks' in Python

[jingham]

Summary

Previously, you could only have a list of command-line commands as the reaction to a stop hook.

This patch adds the ability to define the stop hooks directly in Python, which allows you to do logging and add logic to the stop hook more easily.

[jingham]

Added docs to the python-reference.rst

[kastiglione]

lldb/source/Commands/CommandObjectTarget.cpp

4625

missing space after def

[JDevlieghere]

I'm very excited about this feature. Great job on the documentation, both in the help output as for the website. Do you have a potential use case in mind that we could add to the examples?

lldb/docs/use/python-reference.rst

843

Any reason for the double empty lines?

863

There needs to be a newline here for this to be rendered as code.

lldb/include/lldb/Interpreter/ScriptInterpreter.h

302

Could this function return an Expected<StructuredData::GenericSP> instead?

lldb/include/lldb/Target/Target.h

1200

Can we drop this altogether? We can always get the address of the reference at the call site.

1202

can this be a const reference? Maybe even a StringRef? Similar question for the methods below.

1232

Please make these Doxygen comments (///) and put them on the line above the variable.

1238

///

1248–1249

And you might as well fix that here too :-)

1249–1255

I think we should make this a little enum that has the values command and scripted.

lldb/source/Commands/CommandObjectTarget.cpp

4691

Is this used?

lldb/source/Target/Target.cpp

3153

So many early returns in this patch 😍

3273

It looks like we will leak this if script_interp is null. One solution for that would be to wrap it in a unique_ptr and release it when passing it to CreateScriptedStopHook. If we do the m_extra_args assignment just before that call that also guarantees that the variable remains null until then.

[jingham]

Addressed review comments.

[jingham]

Addressed review comments.

lldb/docs/use/python-reference.rst

843

Nope.

lldb/include/lldb/Interpreter/ScriptInterpreter.h

302

There are a bunch of instances of objects created to insert scripting into various lldb callbacks around in lldb. It might make sense to convert them all to Expected's, but I wouldn't want to do it piecemeal.

Adding a new one of these is also a bit cargo-culty (another issue we should probably clean up as a separate bit of work) and so making the same things look different is not doing the next person who adds one any favors.

These are also functions that are not going to get called promiscuously, but really from one "make me one of these" places, so they aren't crying out for protection against calling them w/o checking for errors.

But anyway, IMO if we're going to start restructuring the pattern for setting these callback objects up, we should do that as a separate commit and do it for all of them.

lldb/include/lldb/Target/Target.h

1202

const is fine. Since all I plan to do is pass this string to a function that takes a const std::string, it doesn't make much sense to make it a StringRef.

1232

I didn't quite do that.

The comment about "We own..." doesn't seem to me to be a doc comment. It isn't something that a user of this stop hook class would need to know. It's just an answer to a question somebody reading the code closely might ask about why we don't have to have something keeping this m_extra_args alive. I did add a doc comment for this field, but kept the side comment as is.

lldb/source/Commands/CommandObjectTarget.cpp

4691

Nope. Vestigial from an older draft of the StopHook API's.

lldb/source/Target/Target.cpp

3273

I did this more simple-mindedly by just checking for the script interpreter before we do any other work.

[JDevlieghere]

lldb/include/lldb/Interpreter/ScriptInterpreter.h

302

If I counted correctly there are 2 others: CreateScriptedThreadPlan which takes a std::string& as an error and CreateScriptedBreakpointResolver which doesn't seem to do error handling at all. So I think we should try to refactor all three to return Expecteds. I agree we should do that in a separate patch.

lldb/include/lldb/Target/Target.h

1232

It's private anyway, so I think the boundaries are pretty fluid. But I don't feel strongly about it.

[davezarzycki]

Hi Jim, this change broke my Fedora 33 Linux (x86) box. Do you think we can get a quick fix or revert this?

FAIL: lldb-shell :: Commands/command-stop-hook-output.test (69796 of 70913)
******************** TEST 'lldb-shell :: Commands/command-stop-hook-output.test' FAILED ********************
Script:
--
: 'RUN: at line 1';   /tmp/_update_lc/r/bin/clang --target=specify-a-target-or-use-a-_host-substitution --target=x86_64-unknown-linux-gnu -pthread -fmodules-cache-path=/tmp/_update_lc/r/lldb-test-build.noindex/module-cache-clang/lldb-shell -g /home/dave/ro_s/lp/lldb/test/Shell/Commands/Inputs/main.c -o /tmp/_update_lc/r/tools/lldb/test/Commands/Output/command-stop-hook-output.test.tmp
: 'RUN: at line 2';   /tmp/_update_lc/r/bin/lldb --no-lldbinit -S /tmp/_update_lc/r/tools/lldb/test/Shell/lit-lldb-init /tmp/_update_lc/r/tools/lldb/test/Commands/Output/command-stop-hook-output.test.tmp -O 'command script import /home/dave/ro_s/lp/lldb/test/Shell/Commands/Inputs/stop_hook.py' -s /home/dave/ro_s/lp/lldb/test/Shell/Commands/command-stop-hook-output.test -o exit | /tmp/_update_lc/r/bin/FileCheck /home/dave/ro_s/lp/lldb/test/Shell/Commands/command-stop-hook-output.test
--
Exit Code: 1

Command Output (stderr):
--
clang-12: warning: argument unused during compilation: '-fmodules-cache-path=/tmp/_update_lc/r/lldb-test-build.noindex/module-cache-clang/lldb-shell' [-Wunused-command-line-argument]
error: module importing failed: This script interpreter does not support importing modules.
/home/dave/ro_s/lp/lldb/test/Shell/Commands/command-stop-hook-output.test:5:16: error: CHECK-LABEL: expected string not found in input
# CHECK-LABEL: b main
               ^
<stdin>:1:1: note: scanning from here
(lldb) command source -s 0 '/tmp/_update_lc/r/tools/lldb/test/Shell/lit-lldb-init'
^
<stdin>:1:8: note: possible intended match here
(lldb) command source -s 0 '/tmp/_update_lc/r/tools/lldb/test/Shell/lit-lldb-init'
       ^

Input file: <stdin>
Check file: /home/dave/ro_s/lp/lldb/test/Shell/Commands/command-stop-hook-output.test

-dump-input=help explains the following input dump.

Input was:
<<<<<<
           1: (lldb) command source -s 0 '/tmp/_update_lc/r/tools/lldb/test/Shell/lit-lldb-init'
label:5'0     X~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ error: no match found
label:5'1            ?                                                                           possible intended match
           2: Executing commands in '/tmp/_update_lc/r/tools/lldb/test/Shell/lit-lldb-init'.
label:5'0     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
           3: (lldb) # LLDB init file for the LIT tests.
label:5'0     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
           4: (lldb) settings set symbols.enable-external-lookup false
label:5'0     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
           5: (lldb) settings set plugin.process.gdb-remote.packet-timeout 60
label:5'0     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
           6: (lldb) settings set interpreter.echo-comment-commands false
label:5'0     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
           .
           .
           .
>>>>>>

--

********************
********************
Failed Tests (1):
  lldb-shell :: Commands/command-stop-hook-output.test


Testing Time: 66.80s
  Unsupported      : 10853
  Passed           : 59957
  Expectedly Failed:   102
  Failed           :     1
FAILED: CMakeFiles/check-all

[teemperor]

This also doesn't work on my macOS system:

FAIL: LLDB (/Users/teemperor/1llvm/rel/bin/clang-x86_64) :: test_stop_hooks_scripted_return_false (TestStopHookScripted.TestStopHooks)
======================================================================
FAIL: test_stop_hooks_scripted_return_false (TestStopHookScripted.TestStopHooks)
   Test that the returning False from a stop hook works
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/Users/teemperor/1llvm/llvm-project/lldb/test/API/commands/target/stop-hooks/TestStopHookScripted.py", line 54, in test_stop_hooks_scripted_return_false
    self.do_test_auto_continue(True)
  File "/Users/teemperor/1llvm/llvm-project/lldb/test/API/commands/target/stop-hooks/TestStopHookScripted.py", line 91, in do_test_auto_continue
    self.assertEqual("main", func_name, "Didn't stop at the expected function.")
AssertionError: 'main' != 'step_out_of_me'
- main+ step_out_of_me : Didn't stop at the expected function.
Config=x86_64-/Users/teemperor/1llvm/rel/bin/clang
----------------------------------------------------------------------

lldb/bindings/python/python-swigsafecast.swig

 }
 
 template <>
 PyObject*
 SBTypeToSWIGWrapper (lldb::SBSymbolContext* sym_ctx_sb)
 {
     return SWIG_NewPointerObj((void *) sym_ctx_sb, SWIGTYPE_p_lldb__SBSymbolContext, 0);
 }
+
+template <>
+PyObject*
+SBTypeToSWIGWrapper (lldb::SBStream* stream_sb)
+{
+    return SWIG_NewPointerObj((void *) stream_sb, SWIGTYPE_p_lldb__SBStream, 0);
+}

lldb/bindings/python/python-wrapper.swig

if (PyErr_Occurred()) {
         PyErr_Print();
         PyErr_Clear();
         return 0;
     }
 
     return ret_val;
 }
 
+SWIGEXPORT void *
+LLDBSwigPythonCreateScriptedStopHook
+(
+    lldb::TargetSP target_sp,
+    const char *python_class_name,
+    const char *session_dictionary_name,
+    lldb_private::StructuredDataImpl *args_impl,
+    Status &error
+)
+{
+    if (python_class_name == NULL || python_class_name[0] == '\0') {
+        error.SetErrorString("Empty class name.");
+        Py_RETURN_NONE;
+    }
+    if (!session_dictionary_name) {
+      error.SetErrorString("No session dictionary");
+      Py_RETURN_NONE;
+    }
+    
+    PyErr_Cleaner py_err_cleaner(true);
+
+    auto dict = 
+        PythonModule::MainModule().ResolveName<PythonDictionary>(
+            session_dictionary_name);
+    auto pfunc = 
+        PythonObject::ResolveNameWithDictionary<PythonCallable>(
+            python_class_name, dict);
+
+    if (!pfunc.IsAllocated()) {
+        error.SetErrorStringWithFormat("Could not find class: %s.", 
+                                       python_class_name);
+        return nullptr;
+    }
+
+    lldb::SBTarget *target_val 
+        = new lldb::SBTarget(target_sp);
+
+    PythonObject target_arg(PyRefType::Owned, SBTypeToSWIGWrapper(target_val));
+
+    lldb::SBStructuredData *args_value = new lldb::SBStructuredData(args_impl);
+    PythonObject args_arg(PyRefType::Owned, SBTypeToSWIGWrapper(args_value));
+
+    PythonObject result = pfunc(target_arg, args_arg, dict);
+
+    if (result.IsAllocated())
+    {
+        // Check that the handle_stop callback is defined:
+        auto callback_func = result.ResolveName<PythonCallable>("handle_stop");
+        if (callback_func.IsAllocated()) {
+          if (auto args_info = callback_func.GetArgInfo()) {
+            if ((*args_info).max_positional_args < 2) {
+              error.SetErrorStringWithFormat("Wrong number of args for "
+              "handle_stop callback, should be 2 (excluding self), got: %d", 
+              (*args_info).max_positional_args);
+            } else
+              return result.release();
+          } else {
+            error.SetErrorString("Couldn't get num arguments for handle_stop "
+                                 "callback.");
+          }
+          return result.release();
+        }
+        else {
+          error.SetErrorStringWithFormat("Class \"%s\" is missing the required "
+                                         "handle_stop callback.");
+          result.release();
+        }
+    }
+    Py_RETURN_NONE;
+}
+
+SWIGEXPORT bool
+LLDBSwigPythonStopHookCallHandleStop
+(
+    void *implementor,
+    lldb::ExecutionContextRefSP exc_ctx_sp,
+    lldb::StreamSP stream
+)
+{
+    // handle_stop will return a bool with the meaning "should_stop"...
+    // If you return nothing we'll assume we are going to stop.
+    // Also any errors should return true, since we should stop on error.
+
+    PyErr_Cleaner py_err_cleaner(false);
+    PythonObject self(PyRefType::Borrowed, static_cast<PyObject*>(implementor));
+    auto pfunc = self.ResolveName<PythonCallable>("handle_stop");
+
+    if (!pfunc.IsAllocated())
+        return true;
+
+    PythonObject result;
+    lldb::SBExecutionContext sb_exc_ctx(exc_ctx_sp);
+    PythonObject exc_ctx_arg(PyRefType::Owned, SBTypeToSWIGWrapper(sb_exc_ctx));
+    lldb::SBStream sb_stream;
+    PythonObject sb_stream_arg(PyRefType::Owned, 
+                               SBTypeToSWIGWrapper(sb_stream));
+    result = pfunc(exc_ctx_arg, sb_stream_arg);
+
+    if (PyErr_Occurred())
+    {
+        stream->PutCString("Python error occurred handling stop-hook.");
+        PyErr_Print();
+        PyErr_Clear();
+        return true;
+    }
+    
+    // Now add the result to the output stream.  SBStream only
+    // makes an internally help StreamString which I can't interpose, so I 
+    // have to copy it over here.
+    stream->PutCString(sb_stream.GetData());
+    
+    if (result.get() == Py_False)
+      return false;
+    else
+      return true;
+}
+
 // wrapper that calls an optional instance member of an object taking no arguments
 static PyObject*
 LLDBSwigPython_CallOptionalMember
 (
     PyObject* implementor,
     char* callee_name,
     PyObject* ret_if_not_found = Py_None,
     bool* was_found = NULL

lldb/docs/use/python-reference.rst

::
 
   (lldb) b read
   (lldb) r
   Process 1234 stopped
   * thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.3
       frame #0: 0x00007fff06013ca0 libsystem_kernel.dylib`read
   (lldb) frame variable
   (int) fd = 3
+
+ Writing Target Stop-Hooks in Python:
+ ------------------------------------
+
+ Stop hooks fire whenever the process stops just before control is returned to the
+ user.  Stop hooks can either be a set of lldb command-line commands, or can
+ be implemented by a suitably defined Python class.  The Python based stop-hooks
+ can also be passed as set of -key -value pairs when they are added, and those
+ will get packaged up into a SBStructuredData Dictionary and passed to the
+ constructor of the Python object managing the stop hook.  This allows for
+ parametrization of the stop hooks.
+
+ To add a Python-based stop hook, first define a class with the following methods:
+
++--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
+| Name               | Arguments                             | Description                                                                                                      |
++--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
+| **__init__**       | **target: lldb.SBTarget**             | This is the constructor for the new stop-hook.                                                                   |
+|                    | **extra_args: lldb.SBStructuredData** |                                                                                                                  |
+|                    |                                       |                                                                                                                  |
+|                    |                                       | **target** is the SBTarget to which the stop hook is added.                                                      |
+|                    |                                       |                                                                                                                  |
+|                    |                                       | **extra_args** is an SBStructuredData object that the user can pass in when creating instances of this           |
+|                    |                                       | breakpoint.  It is not required, but allows for reuse of stop-hook classes.                                      |
++--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
+| **handle_stop**    | **exe_ctx: lldb.SBExecutionContext**  | This is the called when the target stops.                                                                        |
+|                    | **stream: lldb.SBStream**             |                                                                                                                  |
+|                    |                                       | **exe_ctx** argument will be filled with the current stop point for which the stop hook is                       |
+|                    |                                       | being evaluated.                                                                                                 |
+|                    |                                       |                                                                                                                  |
+|                    |                                       | **stream** an lldb.SBStream, anything written to this stream will be written to the debugger console.            |
+|                    |                                       |                                                                                                                  |
+|                    |                                       | The return value is a "Should Stop" vote from this thread.  If the method returns either True or no return       |
+|                    |                                       | this thread votes to stop.  If it returns False, then the thread votes to continue after all the stop-hooks      |
+|                    |                                       | are evaluated.                                                                                                   |
+|                    |                                       | Note, the --auto-continue flag to 'target stop-hook add' overrides a True return value from the method.          |
++--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
+
+To use this class in lldb, run the command:
+
+::
+
+   (lldb) command script import MyModule.py
+   (lldb) target stop-hook add -P MyModule.MyStopHook -k first -v 1 -k second -v 2
+
+where MyModule.py is the file containing the class definition MyStopHook.

lldb/include/lldb/Interpreter/ScriptInterpreter.h

 //===-- ScriptInterpreter.h -------------------------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef LLDB_INTERPRETER_SCRIPTINTERPRETER_H
 #define LLDB_INTERPRETER_SCRIPTINTERPRETER_H
 
 #include "lldb/Breakpoint/BreakpointOptions.h"
 #include "lldb/Core/Communication.h"
 #include "lldb/Core/PluginInterface.h"
 #include "lldb/Core/SearchFilter.h"
 #include "lldb/Core/StreamFile.h"
 #include "lldb/Host/PseudoTerminal.h"
 #include "lldb/Utility/Broadcaster.h"
 #include "lldb/Utility/Status.h"
 #include "lldb/Utility/StructuredData.h"
public:
   }
 
   virtual lldb::SearchDepth
   ScriptedBreakpointResolverSearchDepth(StructuredData::GenericSP implementor_sp)
   {
     return lldb::eSearchDepthModule;
   }
 
+  virtual StructuredData::GenericSP
+  CreateScriptedStopHook(lldb::TargetSP target_sp, const char *class_name,
+                         StructuredDataImpl *args_data, Status &error) {
+    error.SetErrorString("Creating scripted stop-hooks with the current "
+                         "script interpreter is not supported.");
+    return StructuredData::GenericSP();
+  }
+
+  // This dispatches to the handle_stop method of the stop-hook class.  It
+  // returns a "should_stop" bool.
+  virtual bool
+  ScriptedStopHookHandleStop(StructuredData::GenericSP implementor_sp,
+                             ExecutionContext &exc_ctx,
+                             lldb::StreamSP stream_sp) {
+    return true;
+  }
+
   virtual StructuredData::ObjectSP
   LoadPluginModule(const FileSpec &file_spec, lldb_private::Status &error) {
     return StructuredData::ObjectSP();
   }
 
   virtual StructuredData::DictionarySP
   GetDynamicSettings(StructuredData::ObjectSP plugin_module_sp, Target *target,
                      const char *setting_name, lldb_private::Status &error) {

lldb/include/lldb/Symbol/SymbolContext.h

 //===-- SymbolContext.h -----------------------------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef LLDB_SYMBOL_SYMBOLCONTEXT_H
 #define LLDB_SYMBOL_SYMBOLCONTEXT_H
 
 #include <memory>
 #include <string>
 #include <vector>
 
 #include "lldb/Core/Address.h"
 #include "lldb/Core/Mangled.h"
 #include "lldb/Symbol/LineEntry.h"
 #include "lldb/Utility/Iterable.h"
 #include "lldb/lldb-private.h"
 
 namespace lldb_private {
 
 class SymbolContextScope;
public:
   ~SymbolContextSpecifier();
 
   bool AddSpecification(const char *spec_string, SpecificationType type);
 
   bool AddLineSpecification(uint32_t line_no, SpecificationType type);
 
   void Clear();
 
-  bool SymbolContextMatches(SymbolContext &sc);
+  bool SymbolContextMatches(const SymbolContext &sc);
 
   bool AddressMatches(lldb::addr_t addr);
 
   void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
 
 private:
   lldb::TargetSP m_target_sp;
   std::string m_module_spec;

lldb/include/lldb/Target/Target.h

 #define LLDB_TARGET_TARGET_H
 
 #include <list>
 #include <map>
 #include <memory>
 #include <string>
 #include <vector>
 
 #include "lldb/Breakpoint/BreakpointList.h"
 #include "lldb/Breakpoint/BreakpointName.h"
 #include "lldb/Breakpoint/WatchpointList.h"
 #include "lldb/Core/Architecture.h"
 #include "lldb/Core/Disassembler.h"
 #include "lldb/Core/ModuleList.h"
 #include "lldb/Core/UserSettingsController.h"
 #include "lldb/Expression/Expression.h"
 #include "lldb/Host/ProcessLaunchInfo.h"
 #include "lldb/Symbol/TypeSystem.h"
 #include "lldb/Target/ExecutionContextScope.h"
 #include "lldb/Target/PathMappingList.h"
 #include "lldb/Target/SectionLoadHistory.h"
+#include "lldb/Target/ThreadSpec.h"
 #include "lldb/Utility/ArchSpec.h"
 #include "lldb/Utility/Broadcaster.h"
 #include "lldb/Utility/LLDBAssert.h"
 #include "lldb/Utility/Timeout.h"
 #include "lldb/lldb-public.h"
 
 namespace lldb_private {
 
public:
   static FileSpecList GetDefaultExecutableSearchPaths();
 
   static FileSpecList GetDefaultDebugFileSearchPaths();
 
   static ArchSpec GetDefaultArchitecture();
 
   static void SetDefaultArchitecture(const ArchSpec &arch);
 
+  bool IsDummyTarget() const { return m_is_dummy_target; }
+
   /// Find a binary on the system and return its Module,
   /// or return an existing Module that is already in the Target.
   ///
   /// Given a ModuleSpec, find a binary satisifying that specification,
   /// or identify a matching Module already present in the Target,
   /// and return a shared pointer to it.
   ///
   /// \param[in] module_spec
public:
   ///     Returns the entry address for this program, or an error
   ///     if none can be found.
   llvm::Expected<lldb_private::Address> GetEntryPointAddress();
 
   // Target Stop Hooks
   class StopHook : public UserID {
   public:
     StopHook(const StopHook &rhs);
+    virtual ~StopHook() = default;
 
-    ~StopHook();
-
-    StringList *GetCommandPointer() { return &m_commands; }
-
-    const StringList &GetCommands() { return m_commands; }
+    enum class StopHookKind  : uint32_t { CommandBased = 0, ScriptBased };
 
     lldb::TargetSP &GetTarget() { return m_target_sp; }
 
-    void SetCommands(StringList &in_commands) { m_commands = in_commands; }
-
     // Set the specifier.  The stop hook will own the specifier, and is
     // responsible for deleting it when we're done.
     void SetSpecifier(SymbolContextSpecifier *specifier);
 
     SymbolContextSpecifier *GetSpecifier() { return m_specifier_sp.get(); }
 
+    bool ExecutionContextPasses(const ExecutionContext &exe_ctx);
+
+    // Called on stop, this gets passed the ExecutionContext for each "stop
+    // with a reason" thread.  It should add to the stream whatever text it
+    // wants to show the user, and return False to indicate it wants the target
+    // not to stop.
+    virtual bool HandleStop(ExecutionContext &exe_ctx,
+                            lldb::StreamSP output) = 0;
+
     // Set the Thread Specifier.  The stop hook will own the thread specifier,
     // and is responsible for deleting it when we're done.
     void SetThreadSpecifier(ThreadSpec *specifier);
 
     ThreadSpec *GetThreadSpecifier() { return m_thread_spec_up.get(); }
 
     bool IsActive() { return m_active; }
 
     void SetIsActive(bool is_active) { m_active = is_active; }
 
     void SetAutoContinue(bool auto_continue) {
       m_auto_continue = auto_continue;
     }
 
     bool GetAutoContinue() const { return m_auto_continue; }
 
     void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
+    virtual void GetSubclassDescription(Stream *s,
+                                        lldb::DescriptionLevel level) const = 0;
 
-  private:
+  protected:
     lldb::TargetSP m_target_sp;
-    StringList m_commands;
     lldb::SymbolContextSpecifierSP m_specifier_sp;
     std::unique_ptr<ThreadSpec> m_thread_spec_up;
     bool m_active = true;
     bool m_auto_continue = false;
 
+    StopHook(lldb::TargetSP target_sp, lldb::user_id_t uid);
+  };
+
+  class StopHookCommandLine : public StopHook {
+  public:
+    virtual ~StopHookCommandLine() = default;
+
+    StringList &GetCommands() { return m_commands; }
+    void SetActionFromString(const std::string &strings);
+    void SetActionFromStrings(const std::vector<std::string> &strings);
+
+    bool HandleStop(ExecutionContext &exc_ctx,
+                    lldb::StreamSP output_sp) override;
+    void GetSubclassDescription(Stream *s,
+                                lldb::DescriptionLevel level) const override;
+
+  private:
+    StringList m_commands;
     // Use CreateStopHook to make a new empty stop hook. The GetCommandPointer
     // and fill it with commands, and SetSpecifier to set the specifier shared
     // pointer (can be null, that will match anything.)
-    StopHook(lldb::TargetSP target_sp, lldb::user_id_t uid);
+    StopHookCommandLine(lldb::TargetSP target_sp, lldb::user_id_t uid)
+        : StopHook(target_sp, uid) {}
     friend class Target;
   };
+
+  class StopHookScripted : public StopHook {
+  public:
+    virtual ~StopHookScripted() = default;
+    bool HandleStop(ExecutionContext &exc_ctx, lldb::StreamSP output) override;
+
+    Status SetScriptCallback(std::string class_name,
+                             StructuredData::ObjectSP extra_args_sp);
+
+    void GetSubclassDescription(Stream *s,
+                                lldb::DescriptionLevel level) const override;
+
+  private:
+    std::string m_class_name;
+    /// This holds the dictionary of keys & values that can be used to
+    /// parametrize any given callback's behavior.
+    StructuredDataImpl *m_extra_args; // We own this structured data,
+                                      // but the SD itself manages the UP.
+    /// This holds the python callback object.
+    StructuredData::GenericSP m_implementation_sp; 
+
+    /// Use CreateStopHook to make a new empty stop hook. The GetCommandPointer
+    /// and fill it with commands, and SetSpecifier to set the specifier shared
+    /// pointer (can be null, that will match anything.)
+    StopHookScripted(lldb::TargetSP target_sp, lldb::user_id_t uid)
+        : StopHook(target_sp, uid) {}
+    friend class Target;
+  };
+
   typedef std::shared_ptr<StopHook> StopHookSP;
 
-  // Add an empty stop hook to the Target's stop hook list, and returns a
-  // shared pointer to it in new_hook. Returns the id of the new hook.
-  StopHookSP CreateStopHook();
+  /// Add an empty stop hook to the Target's stop hook list, and returns a
+  /// shared pointer to it in new_hook. Returns the id of the new hook.
+  StopHookSP CreateStopHook(StopHook::StopHookKind kind);
+
+  /// If you tried to create a stop hook, and that failed, call this to
+  /// remove the stop hook, as it will also reset the stop hook counter.
+  void UndoCreateStopHook(lldb::user_id_t uid);
 
   void RunStopHooks();
 
   size_t GetStopHookSize();
 
   bool SetSuppresStopHooks(bool suppress) {
     bool old_value = m_suppress_stop_hooks;
     m_suppress_stop_hooks = suppress;

lldb/source/Commands/CommandObjectTarget.cpp

 #include "lldb/Interpreter/CommandInterpreter.h"
 #include "lldb/Interpreter/CommandReturnObject.h"
 #include "lldb/Interpreter/OptionArgParser.h"
 #include "lldb/Interpreter/OptionGroupArchitecture.h"
 #include "lldb/Interpreter/OptionGroupBoolean.h"
 #include "lldb/Interpreter/OptionGroupFile.h"
 #include "lldb/Interpreter/OptionGroupFormat.h"
 #include "lldb/Interpreter/OptionGroupPlatform.h"
+#include "lldb/Interpreter/OptionGroupPythonClassWithDict.h"
 #include "lldb/Interpreter/OptionGroupString.h"
 #include "lldb/Interpreter/OptionGroupUInt64.h"
 #include "lldb/Interpreter/OptionGroupUUID.h"
 #include "lldb/Interpreter/OptionGroupValueObjectDisplay.h"
 #include "lldb/Interpreter/OptionGroupVariable.h"
 #include "lldb/Interpreter/Options.h"
 #include "lldb/Symbol/CompileUnit.h"
 #include "lldb/Symbol/FuncUnwinders.h"

 
 // CommandObjectTargetStopHookAdd
 #define LLDB_OPTIONS_target_stop_hook_add
 #include "CommandOptions.inc"
 
 class CommandObjectTargetStopHookAdd : public CommandObjectParsed,
                                        public IOHandlerDelegateMultiline {
 public:
-  class CommandOptions : public Options {
+  class CommandOptions : public OptionGroup {
   public:
     CommandOptions()
-        : Options(), m_line_start(0), m_line_end(UINT_MAX),
+        : OptionGroup(), m_line_start(0), m_line_end(UINT_MAX),
           m_func_name_type_mask(eFunctionNameTypeAuto),
           m_sym_ctx_specified(false), m_thread_specified(false),
           m_use_one_liner(false), m_one_liner() {}
 
     ~CommandOptions() override = default;
 
     llvm::ArrayRef<OptionDefinition> GetDefinitions() override {
       return llvm::makeArrayRef(g_target_stop_hook_add_options);
     }
 
     Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_arg,
                           ExecutionContext *execution_context) override {
       Status error;
-      const int short_option = m_getopt_table[option_idx].val;
+      const int short_option =
+          g_target_stop_hook_add_options[option_idx].short_option;
 
       switch (short_option) {
       case 'c':
         m_class_name = std::string(option_arg);
         m_sym_ctx_specified = true;
         break;
 
       case 'e':
public:
     std::string m_thread_name;
     std::string m_queue_name;
     bool m_sym_ctx_specified;
     bool m_no_inlines;
     bool m_thread_specified;
     // Instance variables to hold the values for one_liner options.
     bool m_use_one_liner;
     std::vector<std::string> m_one_liner;
+
     bool m_auto_continue;
   };
 
   CommandObjectTargetStopHookAdd(CommandInterpreter &interpreter)
       : CommandObjectParsed(interpreter, "target stop-hook add",
-                            "Add a hook to be executed when the target stops.",
+                            "Add a hook to be executed when the target stops."
+                            "The hook can either be a list of commands or an "
+                            "appropriately defined Python class.  You can also "
+                            "add filters so the hook only runs a certain stop "
+                            "points.",
                             "target stop-hook add"),
         IOHandlerDelegateMultiline("DONE",
                                    IOHandlerDelegate::Completion::LLDBCommand),
-        m_options() {}
+        m_options(), m_python_class_options("scripted stop-hook", true, 'P') {
+    SetHelpLong(
+        R"(
+Command Based stop-hooks:
+-------------------------
+  Stop hooks can run a list of lldb commands by providing one or more
+  --one-line-command options.  The commands will get run in the order they are 
+  added.  Or you can provide no commands, in which case you will enter a
+  command editor where you can enter the commands to be run.
+  
+Python Based Stop Hooks:
+------------------------
+  Stop hooks can be implemented with a suitably defined Python class, whose name
+  is passed in the --python-class option.
+  
+  When the stop hook is added, the class is initialized by calling:
+  
+    def __init__(self, target, extra_args, dict):
+    
+    target: The target that the stop hook is being added to.
+    extra_args: An SBStructuredData Dictionary filled with the -key -value 
+                option pairs passed to the command.     
+    dict: An implementation detail provided by lldb.
+
+  Then when the stop-hook triggers, lldb will run the 'handle_stop' method. 
+  The method has the signature:
+  
+    def handle_stop(self, exe_ctx, stream):
+    
+    exe_ctx: An SBExecutionContext for the thread that has stopped.
+    stream: An SBStream, anything written to this stream will be printed in the
+            the stop message when the process stops.
+
+    Return Value: The method returns "should_stop".  If should_stop is false
+                  from all the stop hook executions on threads that stopped
+                  with a reason, then the process will continue.  Note that this
+                  will happen only after all the stop hooks are run.
+    
+Filter Options:
+---------------
+  Stop hooks can be set to always run, or to only run when the stopped thread
+  matches the filter options passed on the command line.  The available filter
+  options include a shared library or a thread or queue specification, 
+  a line range in a source file, a function name or a class name.
+            )");
+    m_all_options.Append(&m_python_class_options,
+                         LLDB_OPT_SET_1 | LLDB_OPT_SET_2,
+                         LLDB_OPT_SET_FROM_TO(4, 6));
+    m_all_options.Append(&m_options);
+    m_all_options.Finalize();
+  }
 
   ~CommandObjectTargetStopHookAdd() override = default;
 
-  Options *GetOptions() override { return &m_options; }
+  Options *GetOptions() override { return &m_all_options; }
 
 protected:
   void IOHandlerActivated(IOHandler &io_handler, bool interactive) override {
     StreamFileSP output_sp(io_handler.GetOutputStreamFileSP());
     if (output_sp && interactive) {
       output_sp->PutCString(
           "Enter your stop hook command(s).  Type 'DONE' to end.\n");
       output_sp->Flush();
     }
   }
 
   void IOHandlerInputComplete(IOHandler &io_handler,
                               std::string &line) override {
     if (m_stop_hook_sp) {
       if (line.empty()) {
         StreamFileSP error_sp(io_handler.GetErrorStreamFileSP());
         if (error_sp) {
           error_sp->Printf("error: stop hook #%" PRIu64
                            " aborted, no commands.\n",
                            m_stop_hook_sp->GetID());
           error_sp->Flush();
         }
         Target *target = GetDebugger().GetSelectedTarget().get();
-        if (target)
-          target->RemoveStopHookByID(m_stop_hook_sp->GetID());
+        if (target) {
+          target->UndoCreateStopHook(m_stop_hook_sp->GetID());
+        }
       } else {
-        m_stop_hook_sp->GetCommandPointer()->SplitIntoLines(line);
+        // The IOHandler editor is only for command lines stop hooks:
+        Target::StopHookCommandLine *hook_ptr =
+            static_cast<Target::StopHookCommandLine *>(m_stop_hook_sp.get());
+
+        hook_ptr->SetActionFromString(line);
         StreamFileSP output_sp(io_handler.GetOutputStreamFileSP());
         if (output_sp) {
           output_sp->Printf("Stop hook #%" PRIu64 " added.\n",
                             m_stop_hook_sp->GetID());
           output_sp->Flush();
         }
       }
       m_stop_hook_sp.reset();
     }
     io_handler.SetIsDone(true);
   }
 
   bool DoExecute(Args &command, CommandReturnObject &result) override {
     m_stop_hook_sp.reset();
 
     Target &target = GetSelectedOrDummyTarget();
-    Target::StopHookSP new_hook_sp = target.CreateStopHook();
+    Target::StopHookSP new_hook_sp =
+        target.CreateStopHook(m_python_class_options.GetName().empty() ?
+                               Target::StopHook::StopHookKind::CommandBased
+                               : Target::StopHook::StopHookKind::ScriptBased);
 
     //  First step, make the specifier.
     std::unique_ptr<SymbolContextSpecifier> specifier_up;
     if (m_options.m_sym_ctx_specified) {
       specifier_up = std::make_unique<SymbolContextSpecifier>(
           GetDebugger().GetSelectedTarget());
 
       if (!m_options.m_module_name.empty()) {
if (m_options.m_thread_specified) {
       if (!m_options.m_queue_name.empty())
         thread_spec->SetQueueName(m_options.m_queue_name.c_str());
 
       new_hook_sp->SetThreadSpecifier(thread_spec);
     }
 
     new_hook_sp->SetAutoContinue(m_options.m_auto_continue);
     if (m_options.m_use_one_liner) {
-      // Use one-liners.
-      for (auto cmd : m_options.m_one_liner)
-        new_hook_sp->GetCommandPointer()->AppendString(cmd.c_str());
+      // This is a command line stop hook:
+      Target::StopHookCommandLine *hook_ptr =
+          static_cast<Target::StopHookCommandLine *>(new_hook_sp.get());
+      hook_ptr->SetActionFromStrings(m_options.m_one_liner);
       result.AppendMessageWithFormat("Stop hook #%" PRIu64 " added.\n",
                                      new_hook_sp->GetID());
+    } else if (!m_python_class_options.GetName().empty()) {
+      // This is a scripted stop hook:
+      Target::StopHookScripted *hook_ptr =
+          static_cast<Target::StopHookScripted *>(new_hook_sp.get());
+      Status error = hook_ptr->SetScriptCallback(
+          m_python_class_options.GetName(),
+          m_python_class_options.GetStructuredData());
+      if (error.Success())
+        result.AppendMessageWithFormat("Stop hook #%" PRIu64 " added.\n",
+                                       new_hook_sp->GetID());
+      else {
+        // FIXME: Set the stop hook ID counter back.
+        result.AppendErrorWithFormat("Couldn't add stop hook: %s",
+                                     error.AsCString());
+        result.SetStatus(eReturnStatusFailed);
+        target.UndoCreateStopHook(new_hook_sp->GetID());
+        return false;
+      }
     } else {
       m_stop_hook_sp = new_hook_sp;
       m_interpreter.GetLLDBCommandsFromIOHandler("> ",   // Prompt
                                                  *this); // IOHandlerDelegate
     }
     result.SetStatus(eReturnStatusSuccessFinishNoResult);
 
     return result.Succeeded();
   }
 
 private:
   CommandOptions m_options;
+  OptionGroupPythonClassWithDict m_python_class_options;
+  OptionGroupOptions m_all_options;
+
   Target::StopHookSP m_stop_hook_sp;
 };
 
 #pragma mark CommandObjectTargetStopHookDelete
 
 // CommandObjectTargetStopHookDelete
 
 class CommandObjectTargetStopHookDelete : public CommandObjectParsed {

lldb/source/Commands/Options.td

def target_modules_lookup_type : Option<"type", "t">, Group<6>, Arg<"Name">,
     "target modules.">;
   def target_modules_lookup_verbose : Option<"verbose", "v">,
     Desc<"Enable verbose lookup information.">;
   def target_modules_lookup_all : Option<"all", "A">, Desc<"Print all matches, "
     "not just the best match, if a best match is available.">;
 }
 
 let Command = "target stop hook add" in {
-  def target_stop_hook_add_one_liner : Option<"one-liner", "o">,
+  def target_stop_hook_add_one_liner : Option<"one-liner", "o">, GroupRange<1,3>,
     Arg<"OneLiner">, Desc<"Add a command for the stop hook.  Can be specified "
     "more than once, and commands will be run in the order they appear.">;
   def target_stop_hook_add_shlib : Option<"shlib", "s">, Arg<"ShlibName">,
     Completion<"Module">,
     Desc<"Set the module within which the stop-hook is to be run.">;
   def target_stop_hook_add_thread_index : Option<"thread-index", "x">,
     Arg<"ThreadIndex">, Desc<"The stop hook is run only for the thread whose "
     "index matches this argument.">;
   def target_stop_hook_add_thread_id : Option<"thread-id", "t">,
     Arg<"ThreadID">, Desc<"The stop hook is run only for the thread whose TID "
     "matches this argument.">;
   def target_stop_hook_add_thread_name : Option<"thread-name", "T">,
     Arg<"ThreadName">, Desc<"The stop hook is run only for the thread whose "
     "thread name matches this argument.">;
   def target_stop_hook_add_queue_name : Option<"queue-name", "q">,
     Arg<"QueueName">, Desc<"The stop hook is run only for threads in the queue "
     "whose name is given by this argument.">;
-  def target_stop_hook_add_file : Option<"file", "f">, Group<1>,
+  def target_stop_hook_add_file : Option<"file", "f">, Groups<[1,4]>,
     Arg<"Filename">, Desc<"Specify the source file within which the stop-hook "
     "is to be run.">, Completion<"SourceFile">;
-  def target_stop_hook_add_start_line : Option<"start-line", "l">, Group<1>,
+  def target_stop_hook_add_start_line : Option<"start-line", "l">, Groups<[1,4]>,
     Arg<"LineNum">, Desc<"Set the start of the line range for which the "
     "stop-hook is to be run.">;
-  def target_stop_hook_add_end_line : Option<"end-line", "e">, Group<1>,
+  def target_stop_hook_add_end_line : Option<"end-line", "e">, Groups<[1,4]>,
     Arg<"LineNum">, Desc<"Set the end of the line range for which the stop-hook"
     " is to be run.">;
-  def target_stop_hook_add_classname : Option<"classname", "c">, Group<2>,
+  def target_stop_hook_add_classname : Option<"classname", "c">, Groups<[2,5]>,
     Arg<"ClassName">,
     Desc<"Specify the class within which the stop-hook is to be run.">;
-  def target_stop_hook_add_name : Option<"name", "n">, Group<3>,
+  def target_stop_hook_add_name : Option<"name", "n">, Groups<[3,6]>,
     Arg<"FunctionName">, Desc<"Set the function name within which the stop hook"
     " will be run.">, Completion<"Symbol">;
   def target_stop_hook_add_auto_continue : Option<"auto-continue", "G">,
     Arg<"Boolean">, Desc<"The breakpoint will auto-continue after running its"
     " commands.">;
 }
 
 let Command = "thread backtrace" in {

lldb/source/Plugins/ScriptInterpreter/Python/ScriptInterpreterPython.cpp

 //===-- ScriptInterpreterPython.cpp ---------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "lldb/Host/Config.h"
 
 #if LLDB_ENABLE_PYTHON
 
 // LLDB Python header must be included first
 #include "lldb-python.h"
 
 #include "PythonDataObjects.h"
 #include "PythonReadline.h"

 extern "C" void *LLDBSwigPythonCreateScriptedBreakpointResolver(
     const char *python_class_name, const char *session_dictionary_name,
     lldb_private::StructuredDataImpl *args, lldb::BreakpointSP &bkpt_sp);
 
 extern "C" unsigned int
 LLDBSwigPythonCallBreakpointResolver(void *implementor, const char *method_name,
                                      lldb_private::SymbolContext *sym_ctx);
 
+extern "C" void *LLDBSwigPythonCreateScriptedStopHook(
+    TargetSP target_sp, const char *python_class_name,
+    const char *session_dictionary_name, lldb_private::StructuredDataImpl *args,
+    lldb_private::Status &error);
+
+extern "C" unsigned int
+LLDBSwigPythonStopHookCallHandleStop(void *implementor,
+                                     lldb::ExecutionContextRefSP exc_ctx,
+                                     lldb::StreamSP stream);
+
 extern "C" size_t LLDBSwigPython_CalculateNumChildren(void *implementor,
                                                       uint32_t max);
 
 extern "C" void *LLDBSwigPython_GetChildAtIndex(void *implementor,
                                                 uint32_t idx);
 
 extern "C" int LLDBSwigPython_GetIndexOfChildWithName(void *implementor,
                                                       const char *child_name);
ScriptInterpreterPythonImpl::ScriptedBreakpointResolverSearchDepth(
   if (depth_as_int == lldb::eSearchDepthInvalid)
     return lldb::eSearchDepthModule;
 
   if (depth_as_int <= lldb::kLastSearchDepthKind)
     return (lldb::SearchDepth)depth_as_int;
   return lldb::eSearchDepthModule;
 }
 
+StructuredData::GenericSP ScriptInterpreterPythonImpl::CreateScriptedStopHook(
+    TargetSP target_sp, const char *class_name, StructuredDataImpl *args_data,
+    Status &error) {
+
+  if (!target_sp) {
+    error.SetErrorString("No target for scripted stop-hook.");
+    return StructuredData::GenericSP();
+  }
+
+  if (class_name == nullptr || class_name[0] == '\0') {
+    error.SetErrorString("No class name for scripted stop-hook.");
+    return StructuredData::GenericSP();
+  }
+
+  ScriptInterpreter *script_interpreter = m_debugger.GetScriptInterpreter();
+  ScriptInterpreterPythonImpl *python_interpreter =
+      static_cast<ScriptInterpreterPythonImpl *>(script_interpreter);
+
+  if (!script_interpreter) {
+    error.SetErrorString("No script interpreter for scripted stop-hook.");
+    return StructuredData::GenericSP();
+  }
+
+  void *ret_val;
+
+  {
+    Locker py_lock(this,
+                   Locker::AcquireLock | Locker::InitSession | Locker::NoSTDIN);
+
+    ret_val = LLDBSwigPythonCreateScriptedStopHook(
+        target_sp, class_name, python_interpreter->m_dictionary_name.c_str(),
+        args_data, error);
+  }
+
+  return StructuredData::GenericSP(new StructuredPythonObject(ret_val));
+}
+
+bool ScriptInterpreterPythonImpl::ScriptedStopHookHandleStop(
+    StructuredData::GenericSP implementor_sp, ExecutionContext &exc_ctx,
+    lldb::StreamSP stream_sp) {
+  assert(implementor_sp &&
+         "can't call a stop hook with an invalid implementor");
+  assert(stream_sp && "can't call a stop hook with an invalid stream");
+
+  Locker py_lock(this,
+                 Locker::AcquireLock | Locker::InitSession | Locker::NoSTDIN);
+
+  lldb::ExecutionContextRefSP exc_ctx_ref_sp(new ExecutionContextRef(exc_ctx));
+
+  bool ret_val = LLDBSwigPythonStopHookCallHandleStop(
+      implementor_sp->GetValue(), exc_ctx_ref_sp, stream_sp);
+  return ret_val;
+}
+
 StructuredData::ObjectSP
 ScriptInterpreterPythonImpl::LoadPluginModule(const FileSpec &file_spec,
                                               lldb_private::Status &error) {
   if (!FileSystem::Instance().Exists(file_spec)) {
     error.SetErrorString("no such file");
     return StructuredData::ObjectSP();
   }
 

lldb/source/Plugins/ScriptInterpreter/Python/ScriptInterpreterPythonImpl.h

 //===-- ScriptInterpreterPythonImpl.h ---------------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "lldb/Host/Config.h"
 
 #if LLDB_ENABLE_PYTHON
 
 #include "lldb-python.h"
 
 #include "PythonDataObjects.h"
 #include "ScriptInterpreterPython.h"
 
public:
   bool ScriptedBreakpointResolverSearchCallback(
       StructuredData::GenericSP implementor_sp,
       SymbolContext *sym_ctx) override;
 
   lldb::SearchDepth ScriptedBreakpointResolverSearchDepth(
       StructuredData::GenericSP implementor_sp) override;
 
   StructuredData::GenericSP
+  CreateScriptedStopHook(lldb::TargetSP target_sp, const char *class_name,
+                         StructuredDataImpl *args_data, Status &error) override;
+
+  bool ScriptedStopHookHandleStop(StructuredData::GenericSP implementor_sp,
+                                  ExecutionContext &exc_ctx,
+                                  lldb::StreamSP stream_sp) override;
+
+  StructuredData::GenericSP
   CreateFrameRecognizer(const char *class_name) override;
 
   lldb::ValueObjectListSP
   GetRecognizedArguments(const StructuredData::ObjectSP &implementor,
                          lldb::StackFrameSP frame_sp) override;
 
   StructuredData::GenericSP
   OSPlugin_CreatePluginObject(const char *class_name,

lldb/source/Symbol/SymbolContext.cpp

 //===-- SymbolContext.cpp -------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "lldb/Symbol/SymbolContext.h"
 
 #include "lldb/Core/Module.h"
 #include "lldb/Core/ModuleSpec.h"
 #include "lldb/Host/Host.h"
 #include "lldb/Host/StringConvert.h"
 #include "lldb/Symbol/Block.h"
 #include "lldb/Symbol/CompileUnit.h"
 #include "lldb/Symbol/ObjectFile.h"
void SymbolContextSpecifier::Clear() {
   m_class_name.clear();
   m_start_line = 0;
   m_end_line = 0;
   m_address_range_up.reset();
 
   m_type = eNothingSpecified;
 }
 
-bool SymbolContextSpecifier::SymbolContextMatches(SymbolContext &sc) {
+bool SymbolContextSpecifier::SymbolContextMatches(const SymbolContext &sc) {
   if (m_type == eNothingSpecified)
     return true;
 
-  if (m_target_sp.get() != sc.target_sp.get())
+  // Only compare targets if this specifier has one and it's not the Dummy
+  // target.  Otherwise if a specifier gets made in the dummy target and
+  // copied over we'll artificially fail the comparision.
+  if (m_target_sp && !m_target_sp->IsDummyTarget() &&
+      m_target_sp != sc.target_sp)
     return false;
 
   if (m_type & eModuleSpecified) {
     if (sc.module_sp) {
       if (m_module_sp.get() != nullptr) {
         if (m_module_sp.get() != sc.module_sp.get())
           return false;
       } else {

lldb/source/Target/Target.cpp

 //===-- Target.cpp --------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "lldb/Target/Target.h"
 #include "Plugins/ExpressionParser/Clang/ClangModulesDeclVendor.h"
 #include "lldb/Breakpoint/BreakpointIDList.h"
 #include "lldb/Breakpoint/BreakpointPrecondition.h"
 #include "lldb/Breakpoint/BreakpointResolver.h"
 #include "lldb/Breakpoint/BreakpointResolverAddress.h"
 #include "lldb/Breakpoint/BreakpointResolverFileLine.h"
 #include "lldb/Breakpoint/BreakpointResolverFileRegex.h"
 #include "lldb/Breakpoint/BreakpointResolverName.h"
if (!m_clang_modules_decl_vendor_up) {
       m_clang_modules_decl_vendor_up.reset(
           ClangModulesDeclVendor::Create(*this));
     }
   }
 
   return m_clang_modules_decl_vendor_up.get();
 }
 
-Target::StopHookSP Target::CreateStopHook() {
+Target::StopHookSP Target::CreateStopHook(StopHook::StopHookKind kind) {
   lldb::user_id_t new_uid = ++m_stop_hook_next_id;
-  Target::StopHookSP stop_hook_sp(new StopHook(shared_from_this(), new_uid));
+  Target::StopHookSP stop_hook_sp;
+  switch (kind) {
+  case StopHook::StopHookKind::CommandBased:
+    stop_hook_sp.reset(new StopHookCommandLine(shared_from_this(), new_uid));
+    break;
+  case StopHook::StopHookKind::ScriptBased:
+    stop_hook_sp.reset(new StopHookScripted(shared_from_this(), new_uid));
+    break;
+  }
   m_stop_hooks[new_uid] = stop_hook_sp;
   return stop_hook_sp;
 }
 
+void Target::UndoCreateStopHook(lldb::user_id_t user_id) {
+  if (!RemoveStopHookByID(user_id))
+    return;
+  if (user_id == m_stop_hook_next_id)
+    m_stop_hook_next_id--;
+}
+
 bool Target::RemoveStopHookByID(lldb::user_id_t user_id) {
   size_t num_removed = m_stop_hooks.erase(user_id);
   return (num_removed != 0);
 }
 
 void Target::RemoveAllStopHooks() { m_stop_hooks.clear(); }
 
 Target::StopHookSP Target::GetStopHookByID(lldb::user_id_t user_id) {
void Target::RunStopHooks() {
   // because of us running a user expression since in that case we do not want
   // to run the stop-hooks
   if (m_process_sp->GetModIDRef().IsLastResumeForUserExpression())
     return;
 
   if (m_stop_hooks.empty())
     return;
 
-  StopHookCollection::iterator pos, end = m_stop_hooks.end();
-
   // If there aren't any active stop hooks, don't bother either.
-  // Also see if any of the active hooks want to auto-continue.
   bool any_active_hooks = false;
-  bool auto_continue = false;
   for (auto hook : m_stop_hooks) {
     if (hook.second->IsActive()) {
       any_active_hooks = true;
-      auto_continue |= hook.second->GetAutoContinue();
+      break;
     }
   }
   if (!any_active_hooks)
     return;
 
-  CommandReturnObject result(m_debugger.GetUseColor());
-
   std::vector<ExecutionContext> exc_ctx_with_reasons;
-  std::vector<SymbolContext> sym_ctx_with_reasons;
 
   ThreadList &cur_threadlist = m_process_sp->GetThreadList();
   size_t num_threads = cur_threadlist.GetSize();
   for (size_t i = 0; i < num_threads; i++) {
     lldb::ThreadSP cur_thread_sp = cur_threadlist.GetThreadAtIndex(i);
     if (cur_thread_sp->ThreadStoppedForAReason()) {
       lldb::StackFrameSP cur_frame_sp = cur_thread_sp->GetStackFrameAtIndex(0);
-      exc_ctx_with_reasons.push_back(ExecutionContext(
-          m_process_sp.get(), cur_thread_sp.get(), cur_frame_sp.get()));
-      sym_ctx_with_reasons.push_back(
-          cur_frame_sp->GetSymbolContext(eSymbolContextEverything));
+      exc_ctx_with_reasons.emplace_back(m_process_sp.get(), cur_thread_sp.get(),
+                                        cur_frame_sp.get());
     }
   }
 
   // If no threads stopped for a reason, don't run the stop-hooks.
   size_t num_exe_ctx = exc_ctx_with_reasons.size();
   if (num_exe_ctx == 0)
     return;
 
-  result.SetImmediateOutputStream(m_debugger.GetAsyncOutputStream());
-  result.SetImmediateErrorStream(m_debugger.GetAsyncErrorStream());
+  StreamSP output_sp = m_debugger.GetAsyncOutputStream();
 
-  bool keep_going = true;
+  bool auto_continue = false;
   bool hooks_ran = false;
   bool print_hook_header = (m_stop_hooks.size() != 1);
   bool print_thread_header = (num_exe_ctx != 1);
-  bool did_restart = false;
+  bool should_stop = false;
+  bool somebody_restarted = false;
 
-  for (pos = m_stop_hooks.begin(); keep_going && pos != end; pos++) {
-    // result.Clear();
-    StopHookSP cur_hook_sp = (*pos).second;
+  for (auto stop_entry : m_stop_hooks) {
+    StopHookSP cur_hook_sp = stop_entry.second;
     if (!cur_hook_sp->IsActive())
       continue;
 
     bool any_thread_matched = false;
-    for (size_t i = 0; keep_going && i < num_exe_ctx; i++) {
-      if ((cur_hook_sp->GetSpecifier() == nullptr ||
-           cur_hook_sp->GetSpecifier()->SymbolContextMatches(
-               sym_ctx_with_reasons[i])) &&
-          (cur_hook_sp->GetThreadSpecifier() == nullptr ||
-           cur_hook_sp->GetThreadSpecifier()->ThreadPassesBasicTests(
-               exc_ctx_with_reasons[i].GetThreadRef()))) {
-        if (!hooks_ran) {
-          hooks_ran = true;
-        }
-        if (print_hook_header && !any_thread_matched) {
-          const char *cmd =
-              (cur_hook_sp->GetCommands().GetSize() == 1
-                   ? cur_hook_sp->GetCommands().GetStringAtIndex(0)
-                   : nullptr);
-          if (cmd)
-            result.AppendMessageWithFormat("\n- Hook %" PRIu64 " (%s)\n",
-                                           cur_hook_sp->GetID(), cmd);
-          else
-            result.AppendMessageWithFormat("\n- Hook %" PRIu64 "\n",
-                                           cur_hook_sp->GetID());
-          any_thread_matched = true;
-        }
+    for (auto exc_ctx : exc_ctx_with_reasons) {
+      // We detect somebody restarted in the stop-hook loop, and broke out of
+      // that loop back to here.  So break out of here too.
+      if (somebody_restarted)
+        break;
+
+      if (!cur_hook_sp->ExecutionContextPasses(exc_ctx))
+        continue;
+
+      // We only consult the auto-continue for a stop hook if it matched the
+      // specifier.
+      auto_continue |= cur_hook_sp->GetAutoContinue();
+
+      if (!hooks_ran)
+
+        StreamString s;
+        cur_hook_sp->GetDescription(&s, eDescriptionLevelBrief);
+        if (s.GetSize() != 0)
+          output_sp->Printf("\n- Hook %" PRIu64 " (%s)\n", cur_hook_sp->GetID(),
+                            s.GetData());
+          output_sp->Printf("\n- Hook %" PRIu64 "\n", cur_hook_sp->GetID());
 
-        if (print_thread_header)
-          result.AppendMessageWithFormat(
-              "-- Thread %d\n",
-              exc_ctx_with_reasons[i].GetThreadPtr()->GetIndexID());
+        output_sp->Printf("-- Thread %d\n",
+                          exc_ctx.GetThreadPtr()->GetIndexID());
 
-        CommandInterpreterRunOptions options;
-        options.SetStopOnContinue(true);
-        options.SetStopOnError(true);
-        options.SetEchoCommands(false);
-        options.SetPrintResults(true);
-        options.SetPrintErrors(true);
-        options.SetAddToHistory(false);
-
-        // Force Async:
-        bool old_async = GetDebugger().GetAsyncExecution();
-        GetDebugger().SetAsyncExecution(true);
-        GetDebugger().GetCommandInterpreter().HandleCommands(
-            cur_hook_sp->GetCommands(), &exc_ctx_with_reasons[i], options,
-            result);
-        GetDebugger().SetAsyncExecution(old_async);
-        // If the command started the target going again, we should bag out of
-        // running the stop hooks.
-        if ((result.GetStatus() == eReturnStatusSuccessContinuingNoResult) ||
-            (result.GetStatus() == eReturnStatusSuccessContinuingResult)) {
-          // But only complain if there were more stop hooks to do:
-          StopHookCollection::iterator tmp = pos;
-          if (++tmp != end)
-            result.AppendMessageWithFormat(
-                "\nAborting stop hooks, hook %" PRIu64
+      bool this_should_stop = cur_hook_sp->HandleStop(exc_ctx, output_sp);
+      // If this hook is set to auto-continue that should override the
+      // HandleStop result...
+      if (cur_hook_sp->GetAutoContinue())
+        this_should_stop = false;
+
+      // If anybody wanted to stop, we should all stop.
+      if (!should_stop)
+        should_stop = this_should_stop;
+
+      // We don't have a good way to prohibit people from restarting the target
+      // willy nilly in a stop hook.  So see if the private state is running
+      // here and bag out if it is.
+      // FIXME: when we are doing non-stop mode for realz we'll have to instead
+      // track each thread, and only bag out if a thread is set running.
+      if (m_process_sp->GetPrivateState() != eStateStopped) {
+        output_sp->Printf("\nAborting stop hooks, hook %" PRIu64
                           " set the program running.\n"
                           "  Consider using '-G true' to make "
                           "stop hooks auto-continue.\n",
                           cur_hook_sp->GetID());
-          keep_going = false;
-          did_restart = true;
-        }
+        somebody_restarted = true;
+        break;
       }
     }
   }
+
+  output_sp->Flush();
+
   // Finally, if auto-continue was requested, do it now:
-  if (!did_restart && auto_continue)
+  // We only compute should_stop against the hook results if a hook got to run
+  // which is why we have to do this conjoint test.
+  if (!somebody_restarted && ((hooks_ran && !should_stop) || auto_continue))
     m_process_sp->PrivateResume();
-
-  result.GetImmediateOutputStream()->Flush();
-  result.GetImmediateErrorStream()->Flush();
 }
 
 const TargetPropertiesSP &Target::GetGlobalProperties() {
   // NOTE: intentional leak so we don't crash if global destructor chain gets
   // called as other threads still use the result of this function
   static TargetPropertiesSP *g_settings_sp_ptr =
       new TargetPropertiesSP(new TargetProperties(nullptr));
   return *g_settings_sp_ptr;
if (info.GetFlags().Test(eLaunchFlagDisableSTDIO)) {
         LLDB_LOG_ERROR(log, std::move(Err), "SetUpPtyRedirection failed: {0}");
       }
     }
   }
 }
 
 // Target::StopHook
 Target::StopHook::StopHook(lldb::TargetSP target_sp, lldb::user_id_t uid)
-    : UserID(uid), m_target_sp(target_sp), m_commands(), m_specifier_sp(),
+    : UserID(uid), m_target_sp(target_sp), m_specifier_sp(),
       m_thread_spec_up() {}
 
 Target::StopHook::StopHook(const StopHook &rhs)
     : UserID(rhs.GetID()), m_target_sp(rhs.m_target_sp),
-      m_commands(rhs.m_commands), m_specifier_sp(rhs.m_specifier_sp),
-      m_thread_spec_up(), m_active(rhs.m_active),
-      m_auto_continue(rhs.m_auto_continue) {
+      m_specifier_sp(rhs.m_specifier_sp), m_thread_spec_up(),
+      m_active(rhs.m_active), m_auto_continue(rhs.m_auto_continue) {
   if (rhs.m_thread_spec_up)
     m_thread_spec_up = std::make_unique<ThreadSpec>(*rhs.m_thread_spec_up);
 }
 
-Target::StopHook::~StopHook() = default;
-
 void Target::StopHook::SetSpecifier(SymbolContextSpecifier *specifier) {
   m_specifier_sp.reset(specifier);
 }
 
 void Target::StopHook::SetThreadSpecifier(ThreadSpec *specifier) {
   m_thread_spec_up.reset(specifier);
 }
 
+bool Target::StopHook::ExecutionContextPasses(const ExecutionContext &exc_ctx) {
+  SymbolContextSpecifier *specifier = GetSpecifier();
+  if (!specifier)
+    return true;
+
+  bool will_run = true;
+  if (exc_ctx.GetFramePtr())
+    will_run = GetSpecifier()->SymbolContextMatches(
+        exc_ctx.GetFramePtr()->GetSymbolContext(eSymbolContextEverything));
+  if (will_run && GetThreadSpecifier() != nullptr)
+    will_run =
+        GetThreadSpecifier()->ThreadPassesBasicTests(exc_ctx.GetThreadRef());
+
+  return will_run;
+}
+
 void Target::StopHook::GetDescription(Stream *s,
                                       lldb::DescriptionLevel level) const {
+
+  // For brief descriptions, only print the subclass description:
+  if (level == eDescriptionLevelBrief) {
+    GetSubclassDescription(s, level);
+    return;
+  }
+
   unsigned indent_level = s->GetIndentLevel();
 
   s->SetIndentLevel(indent_level + 2);
 
   s->Printf("Hook: %" PRIu64 "\n", GetID());
   if (m_active)
     s->Indent("State: enabled\n");
   else
if (m_thread_spec_up) {
     StreamString tmp;
     s->Indent("Thread:\n");
     m_thread_spec_up->GetDescription(&tmp, level);
     s->SetIndentLevel(indent_level + 4);
     s->Indent(tmp.GetString());
     s->PutCString("\n");
     s->SetIndentLevel(indent_level + 2);
   }
+  GetSubclassDescription(s, level);
+}
 
+void Target::StopHookCommandLine::GetSubclassDescription(
+    Stream *s, lldb::DescriptionLevel level) const {
+  // The brief description just prints the first command.
+  if (level == eDescriptionLevelBrief) {
+    if (m_commands.GetSize() == 1)
+      s->PutCString(m_commands.GetStringAtIndex(0));
+    return;
+  }
   s->Indent("Commands: \n");
-  s->SetIndentLevel(indent_level + 4);
+  s->SetIndentLevel(s->GetIndentLevel() + 4);
   uint32_t num_commands = m_commands.GetSize();
   for (uint32_t i = 0; i < num_commands; i++) {
     s->Indent(m_commands.GetStringAtIndex(i));
     s->PutCString("\n");
   }
-  s->SetIndentLevel(indent_level);
+  s->SetIndentLevel(s->GetIndentLevel() - 4);
+}
+
+// Target::StopHookCommandLine
+void Target::StopHookCommandLine::SetActionFromString(const std::string &string) {
+  GetCommands().SplitIntoLines(string);
+}
+
+void Target::StopHookCommandLine::SetActionFromStrings(
+    const std::vector<std::string> &strings) {
+  for (auto string : strings)
+    GetCommands().AppendString(string.c_str());
+}
+
+bool Target::StopHookCommandLine::HandleStop(ExecutionContext &exc_ctx,
+                                             StreamSP output_sp) {
+  assert(exc_ctx.GetTargetPtr() && "Can't call PerformAction on a context "
+                                   "with no target");
+
+  if (!m_commands.GetSize())
+    return true;
+
+  CommandReturnObject result(false);
+  result.SetImmediateOutputStream(output_sp);
+  Debugger &debugger = exc_ctx.GetTargetPtr()->GetDebugger();
+  CommandInterpreterRunOptions options;
+  options.SetStopOnContinue(true);
+  options.SetStopOnError(true);
+  options.SetEchoCommands(false);
+  options.SetPrintResults(true);
+  options.SetPrintErrors(true);
+  options.SetAddToHistory(false);
+
+  // Force Async:
+  bool old_async = debugger.GetAsyncExecution();
+  debugger.SetAsyncExecution(true);
+  debugger.GetCommandInterpreter().HandleCommands(GetCommands(), &exc_ctx,
+                                                  options, result);
+  debugger.SetAsyncExecution(old_async);
+
+  return true;
+}
+
+// Target::StopHookScripted
+Status Target::StopHookScripted::SetScriptCallback(
+    std::string class_name, StructuredData::ObjectSP extra_args_sp) {
+  Status error;
+
+  ScriptInterpreter *script_interp =
+      GetTarget()->GetDebugger().GetScriptInterpreter();
+  if (!script_interp) {
+    error.SetErrorString("No script interpreter installed.");
+    return error;
+  }
+
+  m_class_name = class_name;
+
+  m_extra_args = new StructuredDataImpl();
+
+  if (extra_args_sp)
+    m_extra_args->SetObjectSP(extra_args_sp);
+
+  m_implementation_sp = script_interp->CreateScriptedStopHook(
+      GetTarget(), m_class_name.c_str(), m_extra_args, error);
+
+  return error;
+}
+
+bool Target::StopHookScripted::HandleStop(ExecutionContext &exc_ctx,
+                                          StreamSP output_sp) {
+  assert(exc_ctx.GetTargetPtr() && "Can't call HandleStop on a context "
+                                   "with no target");
+
+  ScriptInterpreter *script_interp =
+      GetTarget()->GetDebugger().GetScriptInterpreter();
+  if (!script_interp)
+    return true;
+
+  bool should_stop = script_interp->ScriptedStopHookHandleStop(
+      m_implementation_sp, exc_ctx, output_sp);
+
+  return should_stop;
+}
+
+void Target::StopHookScripted::GetSubclassDescription(
+    Stream *s, lldb::DescriptionLevel level) const {
+  if (level == eDescriptionLevelBrief) {
+    s->PutCString(m_class_name);
+    return;
+  }
+  s->Indent("Class:");
+  s->Printf("%s\n", m_class_name.c_str());
+
+  // Now print the extra args:
+  // FIXME: We should use StructuredData.GetDescription on the m_extra_args
+  // but that seems to rely on some printing plugin that doesn't exist.
+  if (!m_extra_args->IsValid())
+    return;
+  StructuredData::ObjectSP object_sp = m_extra_args->GetObjectSP();
+  if (!object_sp || !object_sp->IsValid())
+    return;
+
+  StructuredData::Dictionary *as_dict = object_sp->GetAsDictionary();
+  if (!as_dict || !as_dict->IsValid())
+    return;
+
+  uint32_t num_keys = as_dict->GetSize();
+  if (num_keys == 0)
+    return;
+
+  s->Indent("Args:\n");
+  s->SetIndentLevel(s->GetIndentLevel() + 4);
+
+  auto print_one_element = [&s](ConstString key,
+                                StructuredData::Object *object) {
+    s->Indent();
+    s->Printf("%s : %s\n", key.GetCString(),
+              object->GetStringValue().str().c_str());
+    return true;
+  };
+
+  as_dict->ForEach(print_one_element);
+
+  s->SetIndentLevel(s->GetIndentLevel() - 4);
 }
 
 static constexpr OptionEnumValueElement g_dynamic_value_types[] = {
     {
         eNoDynamicValues,
         "no-dynamic-values",
         "Don't calculate the dynamic type of values",
     },

lldb/test/API/commands/target/stop-hooks/TestStopHookScripted.py

+"""
+Test stop hook functionality
+"""
+
+
+
+import lldb
+import lldbsuite.test.lldbutil as lldbutil
+from lldbsuite.test.lldbtest import *
+
+
+class TestStopHooks(TestBase):
+
+    mydir = TestBase.compute_mydir(__file__)
+
+    # If your test case doesn't stress debug info, the
+    # set this to true.  That way it won't be run once for
+    # each debug info format.
+    NO_DEBUG_INFO_TESTCASE = True
+
+    def setUp(self):
+        TestBase.setUp(self)
+        self.build()
+        self.main_source_file = lldb.SBFileSpec("main.c")
+        full_path = os.path.join(self.getSourceDir(), "main.c")
+        self.main_start_line = line_number(full_path, "main()")
+        
+    def not_test_stop_hooks_scripted(self):
+        """Test that a scripted stop hook works with no specifiers"""
+        self.stop_hooks_scripted(5)
+
+    def not_test_stop_hooks_scripted_right_func(self):
+        """Test that a scripted stop hook fires when there is a function match"""
+        self.stop_hooks_scripted(5, "-n step_out_of_me")
+    
+    def not_test_stop_hooks_scripted_wrong_func(self):
+        """Test that a scripted stop hook doesn't fire when the function does not match"""
+        self.stop_hooks_scripted(0, "-n main")
+    
+    def not_test_stop_hooks_scripted_right_lines(self):
+        """Test that a scripted stop hook fires when there is a function match"""
+        self.stop_hooks_scripted(5, "-f main.c -l 1 -e %d"%(self.main_start_line))
+    
+    def not_test_stop_hooks_scripted_wrong_lines(self):
+        """Test that a scripted stop hook doesn't fire when the function does not match"""
+        self.stop_hooks_scripted(0, "-f main.c -l %d -e 100"%(self.main_start_line))
+
+    def not_test_stop_hooks_scripted_auto_continue(self):
+        """Test that the --auto-continue flag works"""
+        self.do_test_auto_continue(False)
+
+    def test_stop_hooks_scripted_return_false(self):
+        """Test that the returning False from a stop hook works"""
+        self.do_test_auto_continue(True)
+
+    def do_test_auto_continue(self, return_true):
+        """Test that auto-continue works."""
+        # We set auto-continue to 1 but the stop hook only applies to step_out_of_me,
+        # so we should end up stopped in main, having run the expression only once.
+        self.script_setup()
+        
+        result = lldb.SBCommandReturnObject()
+
+        if return_true:
+          command = "target stop-hook add -P stop_hook.stop_handler -k increment -v 5 -k return_false -v 1 -n step_out_of_me"
+        else:
+          command = "target stop-hook add -G 1 -P stop_hook.stop_handler -k increment -v 5 -n step_out_of_me"
+            
+        print("Running command: %s"%(command))
+        
+        self.interp.HandleCommand(command, result)
+        self.assertTrue(result.Succeeded, "Set the target stop hook")
+
+        # First run to main.  If we go straight to the first stop hook hit,
+        # run_to_source_breakpoint will fail because we aren't at original breakpoint
+
+        (target, process, thread, bkpt) = lldbutil.run_to_source_breakpoint(self,
+                                   "Stop here first", self.main_source_file)
+
+        # Now set the breakpoint on step_out_of_me, and make sure we run the
+        # expression, then continue back to main.
+        bkpt = target.BreakpointCreateBySourceRegex("Set a breakpoint here and step out", self.main_source_file)
+        self.assertTrue(bkpt.GetNumLocations() > 0, "Got breakpoints in step_out_of_me")
+        process.Continue()
+
+        var = target.FindFirstGlobalVariable("g_var")
+        self.assertTrue(var.IsValid())
+        self.assertEqual(var.GetValueAsUnsigned(), 5, "Updated g_var")
+        
+        func_name = process.GetSelectedThread().frames[0].GetFunctionName()
+        self.assertEqual("main", func_name, "Didn't stop at the expected function.")
+
+    def script_setup(self):
+        self.interp = self.dbg.GetCommandInterpreter()
+        result = lldb.SBCommandReturnObject()
+
+        # Bring in our script file:
+        script_name = os.path.join(self.getSourceDir(), "stop_hook.py")
+        command = "command script import " + script_name
+        self.interp.HandleCommand(command, result)
+        self.assertTrue(result.Succeeded(), "com scr imp failed: %s"%(result.GetError()))
+
+        # set a breakpoint at the end of main to catch our auto-continue tests.
+        # Do it in the dummy target so it will get copied to our target even when
+        # we don't have a chance to stop.
+        dummy_target = self.dbg.GetDummyTarget()
+        dummy_target.BreakpointCreateBySourceRegex("return result", self.main_source_file)
+
+        
+    def stop_hooks_scripted(self, g_var_value, specifier = None):
+        self.script_setup()
+        
+        result = lldb.SBCommandReturnObject()
+
+        command = "target stop-hook add -P stop_hook.stop_handler -k increment -v 5 "
+        if specifier:
+            command += specifier
+        print("Running command: %s"%(command))
+        
+        self.interp.HandleCommand(command, result)
+        self.assertTrue(result.Succeeded, "Set the target stop hook")
+        (target, process, thread, bkpt) = lldbutil.run_to_source_breakpoint(self,
+                                   "Set a breakpoint here", self.main_source_file)
+        # At this point we've hit our stop hook so we should have run our expression,
+        # which increments g_var by the amount specified by the increment key's value.
+        while process.GetState() == lldb.eStateRunning:
+            continue
+
+        var = target.FindFirstGlobalVariable("g_var")
+        self.assertTrue(var.IsValid())
+        self.assertEqual(var.GetValueAsUnsigned(), g_var_value, "Updated g_var")

lldb/test/API/commands/target/stop-hooks/TestStopHooks.py

 """
-Test that stop hooks trigger on "step-out"
+Test stop hook functionality
 """
 
 
 
 import lldb
 import lldbsuite.test.lldbutil as lldbutil
 from lldbsuite.test.lldbtest import *
 
 
 class TestStopHooks(TestBase):
 
     mydir = TestBase.compute_mydir(__file__)
 
     # If your test case doesn't stress debug info, the
     # set this to true.  That way it won't be run once for
     # each debug info format.
     NO_DEBUG_INFO_TESTCASE = True
 
-    def test_stop_hooks_step_out(self):
-        """Test that stop hooks fire on step-out."""
+    def setUp(self):
+        TestBase.setUp(self)
         self.build()
         self.main_source_file = lldb.SBFileSpec("main.c")
+        full_path = os.path.join(self.getSourceDir(), "main.c")
+        self.main_start_line = line_number(full_path, "main()")
+        
+    def test_stop_hooks_step_out(self):
+        """Test that stop hooks fire on step-out."""
         self.step_out_test()
 
     def step_out_test(self):
         (target, process, thread, bkpt) = lldbutil.run_to_source_breakpoint(self,
                                    "Set a breakpoint here", self.main_source_file)
 
         interp = self.dbg.GetCommandInterpreter()
         result = lldb.SBCommandReturnObject()
         interp.HandleCommand("target stop-hook add -o 'expr g_var++'", result)
         self.assertTrue(result.Succeeded, "Set the target stop hook")
         thread.StepOut()
         var = target.FindFirstGlobalVariable("g_var")
         self.assertTrue(var.IsValid())
         self.assertEqual(var.GetValueAsUnsigned(), 1, "Updated g_var")
 
-

lldb/test/API/commands/target/stop-hooks/main.c

 #include <stdio.h>
 
 static int g_var = 0;
 
 int step_out_of_me()
 {
   return g_var; // Set a breakpoint here and step out.
 }
 
 int
 main()
 {
-  return step_out_of_me();
+  int result = step_out_of_me(); // Stop here first
+  return result;
 }

lldb/test/API/commands/target/stop-hooks/stop_hook.py

+import lldb
+
+class stop_handler:
+    def __init__(self, target, extra_args, dict):
+        self.extra_args = extra_args
+        self.target = target
+        self.counter = 0
+        ret_val = self.extra_args.GetValueForKey("return_false")
+        if ret_val:
+            self.ret_val = False
+        else:
+            self.ret_val = True
+
+    def handle_stop(self, exe_ctx, stream):
+        self.counter += 1
+        stream.Print("I have stopped %d times.\n"%(self.counter))
+        increment = 1
+        value = self.extra_args.GetValueForKey("increment")
+        if value:
+            incr_as_str = value.GetStringValue(100)
+            increment = int(incr_as_str)
+        else:
+            stream.Print("Could not find increment in extra_args\n")
+        frame = exe_ctx.GetFrame()
+        expression = "g_var += %d"%(increment)
+        expr_result = frame.EvaluateExpression(expression)
+        if not expr_result.GetError().Success():
+            stream.Print("Error running expression: %s"%(expr_result.GetError().GetCString()))
+        value = exe_ctx.target.FindFirstGlobalVariable("g_var")
+        if not value.IsValid():
+            stream.Print("Didn't get a valid value for g_var.")
+        else:
+            int_val = value.GetValueAsUnsigned()
+        return self.ret_val

lldb/test/Shell/Commands/Inputs/stop_hook.py

+import lldb
+
+class stop_handler:
+    def __init__(self, target, extra_args, dict):
+        self.extra_args = extra_args
+        self.target = target
+
+    def handle_stop(self, exe_ctx, stream):
+        stream.Print("I did indeed run\n")
+        return True

lldb/test/Shell/Commands/command-stop-hook-output.test

+# RUN: %clang_host -g %S/Inputs/main.c -o %t
+# RUN: %lldb %t -O 'command script import %S/Inputs/stop_hook.py' -s %s -o exit | FileCheck %s
+
+b main
+# CHECK-LABEL: b main
+# CHECK: Breakpoint 1: where = {{.*}}`main
+
+target stop-hook add -P stop_hook.stop_handler
+# CHECK-LABEL: target stop-hook add -P stop_hook.stop_handler
+# CHECK: Stop hook #1 added.
+
+run
+# CHECK-LABEL: run
+# CHECK: I did indeed run
+# CHECK: Process {{.*}} stopped
+# CHECK: stop reason = breakpoint 1
+# CHECK:   frame #0: {{.*}}`main at main.c
+

lldb/unittests/ScriptInterpreter/Python/PythonTestSuite.cpp

 //===-- PythonTestSuite.cpp -----------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "gtest/gtest.h"
 
 #include "Plugins/ScriptInterpreter/Python/lldb-python.h"
 
 #include "Plugins/ScriptInterpreter/Python/ScriptInterpreterPython.h"
 #include "Plugins/ScriptInterpreter/Python/ScriptInterpreterPythonImpl.h"
 #include "lldb/Host/FileSystem.h"
 #include "lldb/Host/HostInfo.h"
 
extern "C" bool LLDBSWIGPythonRunScriptKeywordValue(
   return false;
 }
 
 extern "C" void *
 LLDBSWIGPython_GetDynamicSetting(void *module, const char *setting,
                                  const lldb::TargetSP &target_sp) {
   return nullptr;
 }
+
+extern "C" void *LLDBSwigPythonCreateScriptedStopHook(
+    lldb::TargetSP target_sp, const char *python_class_name,
+    const char *session_dictionary_name,
+    lldb_private::StructuredDataImpl *args_impl, Status &error) {
+  return nullptr;
+}
+
+extern "C" bool
+LLDBSwigPythonStopHookCallHandleStop(void *implementor,
+                                     lldb::ExecutionContextRefSP exc_ctx_sp,
+                                     lldb::StreamSP stream) {
+  return false;
+}