Add a Debugger interruption mechanism in parallel to the Command Interpreter interruption

[jingham]

Summary

I put up an RFC for debugger interruption a while back. This is my version of that RFC.

The implementation is based on the way lldb is often used in UI's (as opposed to the simple use in lldb's command driver). In those cases, the lldb client often includes a thread running the LLDB command interpreter so that they can provide an "LLDB Console" window where the user can run commands, and then on other threads they call various SB API's that are used to fill the Threads, Locals, etc. windows.

So it seemed the most useful model was to separate interrupting into "Interrupting commands servicing the Console" and "Interrupting work the client is doing on its own behalf." For instance if the client is filling the Locals view, but then the user issues "continue" in the console, the client would want to interrupt filling the Locals view (e.g. interrupt SBFrame.FindVariables()) so that it can continue right away, but not interrupt the user's "continue" command. Similarly, if the user types some command that's producing lots of output, they want to interrupt that but not stop whatever work the client was doing at the same time.

Another question is how do we tell "Console" window commands from Client commands? Since we provide a nice API that packages up the "run a command interpreter" behavior, it seemed reasonable to have commands run by the thread servicing RunCommandInterpreter be the "Interpreter" commands, and all other threads belong to the client.

This is also convenient because we can programmatically determine which flag we should check when we check the interruption, which allows us to provide a unified API for checking whether an interrupt was requested.

Also, the CommandInterpreter does its job Command by Command, so there's a natural boundary on which to take down the interrupt request. However the client program is really the only agent that can know when it wants to start & stop interruption, so instead of a single InterruptCommand with automatic boundaries, I added explicit raise & lower interrupt flag API's.

One slight ugliness is that we already have SBCommandInterpreter::WasInterrupted(). I could have just left that as the one interface to query for interruption. But long term, I think it makes more sense to think about this as the Debugger figuring out who to interrupt, so I think an SBDebugger::InterruptRequested API is better. Even though I can't remove the old API, I still added the new one.

One other detail you will see in the tests. The current behavior for command interpreter interruption is that if a command is interrupted, we discard the output it has accumulated so far and just return the result "Interrupted..." That's why I had to set the ImmediateOutput file in the test. I'm on the fence about this behavior, so I opted not to change it for now.

[clayborg]

lldb/include/lldb/Core/Debugger.h

398–399

406

Saying "Decrement the interrupt requested _flag_" seems weird. Is this a flag or an interrupt count? Maybe saying "Decrement the interrupt request count of non zero" might be a bit more clear?

[labath]

I kinda like this.

lldb/include/lldb/Core/Debugger.h

565

const on a return value rarely makes sense. OTOH, const on the argument usually does. Did you want this the other way around?

649

I think this is unused

650

can we make this non-recursive?

lldb/source/API/SBDebugger.cpp

1709

bad formatting

lldb/test/API/python_api/was_interrupted/TestDebuggerInterruption.py

40

This had me confused for a while, because "thread local data" has a very specific meaning. Could you rename this to something else?

113

I am confused as to what this lock's purpose is. I can see that it's taken on one thread and released on another (which is in itself an unusual thing to do, even though python permits it), but I still don't understand what does it achieve. Lock are generally used for protecting a certain object. If the goal is to control the interleaving of two threads, then maybe a sequence of barriers would be better. Something like:

#thread 1
work1()
t1_done.wait()
t2_done.wait()
work3()
t1_done.wait()
# etc.. odd-numbered work happens on this thread

#thread 2
t1_done.wait()
work2()
t2_done.wait()
t1_done.wait()
work4()
# etc.. even-numbered work happens here

[jingham]

Converted the test from using a lock to synchronize the command and test threads to using barriers.
Changed the CommandInterpreter to print partial results when commands are interrupted.
I added two more places where we check for interruption:

1. SBFrame::GetVariables
2. StackFrameList::GetFramesUpTo.

I'm still not sure how to actually test these without racing against the operation completing before you get around to the interrupt.

Fixed other review comments.

[jingham]

lldb/test/API/python_api/was_interrupted/TestDebuggerInterruption.py

40

I did intend to use thread local data here - that's why LockContainer derives from threading.local.

The problem is that I have to use the event & lock in the Python command I will run either directly or under RunCommandInterpreter, but I don't have way to explicitly pass python objects to a command when invoking it. I could put the data in globals in the interruptible module. However, since the test variants could be running in parallel this didn't seem like a great idea. So instead I pass the test to the CommandRunner that's going to create my test thread for me, and once it's created its thread, it puts the lock & event in the thread local data, and that's where WelcomeCommand picks it up from. This is probably not 100% necessary, but seemed cleaner to me.

113

Here's a version using barriers exclusively.

[jingham]

Forgot to address Pavel's const comment.

[jingham]

lldb/include/lldb/Core/Debugger.h

565

Neither of these is really const. The incoming thread will get set to be the IOHandler for the debugger which is not really const. Not sure what I was thinking here.

[jingham]

Update the test comments for the new test method.

[bulbazord]

Small nits

lldb/include/lldb/API/SBCommandInterpreter.h

251–253

Some info on the return value would be useful here.

lldb/include/lldb/API/SBDebugger.h

203

Could this be marked const if the mutex was marked mutable?

lldb/include/lldb/Core/Debugger.h

398–399

+1. Also you mention the use of "flag" here but talked about counter before which is inconsistent.

401–402

This method takes no argument message.

[clayborg]

lldb/include/lldb/API/SBDebugger.h

203

We don't tend to mark things in the public API as const because it does nothing when you have a pointer, unique pointer or shared pointer as the only member variable. I guess it would stop you from clearing the pointer, but the "const" does nothing to stop the mutation of the underlying object, and it would be weird to add "const" to all methods just to stop each method from modifying the contents of the member variable.

[jingham]

Fix up some comments.

[jingham]

polite ping... I think I've addressed all the concerns folks raised.

[JDevlieghere]

lldb/source/Core/Debugger.cpp

1252–1253

Nit: else-after-return.

2011–2015

This doesn't look right. You're taking a reference to the old thread, and then immediately change it below. If you want to return the old thread, old_host should be a copy.

[bulbazord]

lldb/source/Core/Debugger.cpp

2011–2015

+1. Does it make sense to use a shared_ptr or a unique_ptr for HostThreads? If so, we could use those.

[JDevlieghere]

lldb/source/Core/Debugger.cpp

2011–2015

I think the HostThread already kind of serves as a wrapper. I think the solution is to either just make a plain copy or call Release() and assign it to the old_host temporary.

[jingham]

Address Jonas' review comment.

[JDevlieghere]

LGTM

lldb/include/lldb/API/SBCommandInterpreter.h

#endif
 
   int HandleCompletionWithDescriptions(const char *current_line,
                                        uint32_t cursor_pos,
                                        int match_start_point,
                                        int max_return_elements,
                                        lldb::SBStringList &matches,
                                        lldb::SBStringList &descriptions);
 
+  /// Returns whether an interrupt flag was raised either by the SBDebugger - 
+  /// when the function is not running on the RunCommandInterpreter thread, or
+  /// by SBCommandInterpreter::InterruptCommand if it is.  If your code is doing
+  /// interruptible work, check this API periodically, and interrupt if it 
+  /// returns true.
   bool WasInterrupted() const;
   
+  /// Interrupts the command currently executing in the RunCommandInterpreter
+  /// thread.
+  ///
+  /// \return
+  ///   \b true if there was a command in progress to recieve the interrupt.
+  ///   \b false if there's no command currently in flight.
+  bool InterruptCommand();
+
   // Catch commands before they execute by registering a callback that will get
   // called when the command gets executed. This allows GUI or command line
   // interfaces to intercept a command and stop it from happening
 #ifndef SWIG
   bool SetCommandOverrideCallback(const char *command_name,
                                   lldb::CommandOverrideCallback callback,
                                   void *baton);
   SBCommandInterpreter(

lldb/include/lldb/API/SBDebugger.h

#endif
 
   void SaveInputTerminalState();
 
   void RestoreInputTerminalState();
 
   lldb::SBCommandInterpreter GetCommandInterpreter();
 
   void HandleCommand(const char *command);
   
+  void RequestInterrupt();
+  void CancelInterruptRequest();
+  bool InterruptRequested();
+
   lldb::SBListener GetListener();
 
 #ifndef SWIG
   void HandleProcessEvent(const lldb::SBProcess &process,
                           const lldb::SBEvent &event, FILE *out,
                           FILE *err); // DEPRECATED
 #endif
 

lldb/include/lldb/Core/Debugger.h

public:
 
   void EnableForwardEvents(const lldb::ListenerSP &listener_sp);
 
   void CancelForwardEvents(const lldb::ListenerSP &listener_sp);
 
   bool IsHandlingEvents() const { return m_event_handler_thread.IsJoinable(); }
 
   Status RunREPL(lldb::LanguageType language, const char *repl_options);
   
+  /// Interruption in LLDB:
+  /// 
+  /// This is a voluntary interruption mechanism, not preemptive.  Parts of lldb
+  /// that do work that can be safely interrupted call 
+  /// Debugger::InterruptRequested and if that returns true, they should return
+  /// at a safe point, shortcutting the rest of the work they were to do.
+  ///  
+  /// lldb clients can both offer a CommandInterpreter (through 
+  /// RunCommandInterpreter) and use the SB API's for their own purposes, so it
+  /// is convenient to separate "interrupting the CommandInterpreter execution"
+  /// and interrupting the work it is doing with the SB API's.  So there are two 
+  /// ways to cause an interrupt: 
+  ///   * CommandInterpreter::InterruptCommand: Interrupts the command currently
+  ///     running in the command interpreter IOHandler thread
+  ///   * Debugger::RequestInterrupt: Interrupts are active on anything but the
+  ///     CommandInterpreter thread till CancelInterruptRequest is called.
+  ///
+  /// Since the two checks are mutually exclusive, however, it's also convenient
+  /// to have just one function to check the interrupt state.
+
+
+  /// Bump the "interrupt requested" count on the debugger to support
+  /// cooperative interruption.  If this is non-zero, InterruptRequested will
+  /// return true.  Interruptible operations are expected to query the
+  /// InterruptRequested API periodically, and interrupt what they were doing
+  /// if it returns \b true.
+  ///
+  void RequestInterrupt();
+  
+  /// Decrement the "interrupt requested" counter.
+  void CancelInterruptRequest();
+  
+  /// This is the correct way to query the state of Interruption.
+  /// If you are on the RunCommandInterpreter thread, it will check the 
+  /// command interpreter state, and if it is on another thread it will 
+  /// check the debugger Interrupt Request state.
+  ///
+  /// \return
+  ///  A boolean value, if \b true an interruptible operation should interrupt
+  ///  itself.
+  bool InterruptRequested();
+
   // This is for use in the command interpreter, when you either want the
   // selected target, or if no target is present you want to prime the dummy
   // target with entities that will be copied over to new targets.
   Target &GetSelectedOrDummyTarget(bool prefer_dummy = false);
   Target &GetDummyTarget() { return *m_dummy_target_sp; }
 
   lldb::BroadcasterManagerSP GetBroadcasterManager() {
     return m_broadcaster_manager_sp;
protected:
 
   void StopEventHandlerThread();
 
   void PushIOHandler(const lldb::IOHandlerSP &reader_sp,
                      bool cancel_top_handler = true);
 
   bool PopIOHandler(const lldb::IOHandlerSP &reader_sp);
 
-  bool HasIOHandlerThread();
+  bool HasIOHandlerThread() const;
 
   bool StartIOHandlerThread();
 
   void StopIOHandlerThread();
   
+  // Sets the IOHandler thread to the new_thread, and returns
+  // the previous IOHandler thread.
+  HostThread SetIOHandlerThread(HostThread &new_thread);
+
   void JoinIOHandlerThread();
   
+  bool IsIOHandlerThreadCurrentThread() const;
+
   lldb::thread_result_t IOHandlerThread();
 
   lldb::thread_result_t DefaultEventHandler();
 
   void HandleBreakpointEvent(const lldb::EventSP &event_sp);
 
   void HandleProcessEvent(const lldb::EventSP &event_sp);
 
protected:
   HostThread m_event_handler_thread;
   HostThread m_io_handler_thread;
   Broadcaster m_sync_broadcaster; ///< Private debugger synchronization.
   Broadcaster m_broadcaster;      ///< Public Debugger event broadcaster.
   lldb::ListenerSP m_forward_listener_sp;
   llvm::once_flag m_clear_once;
   lldb::TargetSP m_dummy_target_sp;
   Diagnostics::CallbackID m_diagnostics_callback_id;
 
   lldb_private::DebuggerDestroyCallback m_destroy_callback = nullptr;
   void *m_destroy_callback_baton = nullptr;
 
+  uint32_t m_interrupt_requested = 0; ///< Tracks interrupt requests
+  std::mutex m_interrupt_mutex;
+
   // Events for m_sync_broadcaster
   enum {
     eBroadcastBitEventThreadIsListening = (1 << 0),
   };
 
 private:
   // Use Debugger::CreateInstance() to get a shared pointer to a new debugger
   // object

lldb/include/lldb/Interpreter/CommandInterpreter.h

public:
   bool HandleCommand(const char *command_line, LazyBool add_to_history,
                      const ExecutionContext &override_context,
                      CommandReturnObject &result);
 
   bool HandleCommand(const char *command_line, LazyBool add_to_history,
                      CommandReturnObject &result,
                      bool force_repeat_command = false);
 
-  bool WasInterrupted() const;
+  bool InterruptCommand();
 
   /// Execute a list of commands in sequence.
   ///
   /// \param[in] commands
   ///    The list of commands to execute.
   /// \param[in,out] context
   ///    The execution context in which to run the commands.
   /// \param[in] options
public:
 
   bool IsInteractive();
 
   bool IOHandlerInterrupt(IOHandler &io_handler) override;
 
 protected:
   friend class Debugger;
 
+  // This checks just the RunCommandInterpreter interruption state.  It is only
+  // meant to be used in Debugger::InterruptRequested
+  bool WasInterrupted() const;
+
   // IOHandlerDelegate functions
   void IOHandlerInputComplete(IOHandler &io_handler,
                               std::string &line) override;
 
   ConstString IOHandlerGetControlSequence(char ch) override {
     if (ch == 'd')
       return ConstString("quit\n");
     return ConstString();
private:
 
   std::atomic<CommandHandlingState> m_command_state{
       CommandHandlingState::eIdle};
 
   int m_iohandler_nesting_level = 0;
 
   void StartHandlingCommand();
   void FinishHandlingCommand();
-  bool InterruptCommand();
 
   Debugger &m_debugger; // The debugger session that this interpreter is
                         // associated with
   // Execution contexts that were temporarily set by some of HandleCommand*
   // overloads.
   std::stack<ExecutionContext> m_overriden_exe_contexts;
   bool m_synchronous_execution;
   bool m_skip_lldbinit_files;

lldb/source/API/SBCommandInterpreter.cpp

bool SBCommandInterpreter::IsActive() {
   LLDB_INSTRUMENT_VA(this);
 
   return (IsValid() ? m_opaque_ptr->IsActive() : false);
 }
 
 bool SBCommandInterpreter::WasInterrupted() const {
   LLDB_INSTRUMENT_VA(this);
 
-  return (IsValid() ? m_opaque_ptr->WasInterrupted() : false);
+  return (IsValid() ? m_opaque_ptr->GetDebugger().InterruptRequested() : false);
+}
+
+bool SBCommandInterpreter::InterruptCommand() {
+  LLDB_INSTRUMENT_VA(this);
+  
+  return (IsValid() ? m_opaque_ptr->InterruptCommand() : false);
 }
 
 const char *SBCommandInterpreter::GetIOHandlerControlSequence(char ch) {
   LLDB_INSTRUMENT_VA(this, ch);
 
   return (IsValid()
               ? m_opaque_ptr->GetDebugger()
                     .GetTopIOHandlerControlSequence(ch)

lldb/source/API/SBDebugger.cpp

 }
 
 SBTrace
 SBDebugger::LoadTraceFromFile(SBError &error,
                               const SBFileSpec &trace_description_file) {
   LLDB_INSTRUMENT_VA(this, error, trace_description_file);
   return SBTrace::LoadTraceFromFile(error, *this, trace_description_file);
 }
+
+void SBDebugger::RequestInterrupt() {
+  LLDB_INSTRUMENT_VA(this);
+  
+  if (m_opaque_sp)
+    m_opaque_sp->RequestInterrupt();  
+}
+void SBDebugger::CancelInterruptRequest()  {
+  LLDB_INSTRUMENT_VA(this);
+  
+  if (m_opaque_sp)
+    m_opaque_sp->CancelInterruptRequest();  
+}
+
+bool SBDebugger::InterruptRequested()   {
+  LLDB_INSTRUMENT_VA(this);
+  
+  if (m_opaque_sp)
+    return m_opaque_sp->InterruptRequested();
+  return false;
+}

lldb/source/API/SBFrame.cpp

 #include <string>
 
 #include "lldb/API/SBFrame.h"
 
 #include "lldb/lldb-types.h"
 
 #include "Utils.h"
 #include "lldb/Core/Address.h"
+#include "lldb/Core/Debugger.h"
 #include "lldb/Core/StreamFile.h"
 #include "lldb/Core/ValueObjectRegister.h"
 #include "lldb/Core/ValueObjectVariable.h"
 #include "lldb/Core/ValueObjectConstResult.h"
 #include "lldb/Expression/ExpressionVariable.h"
 #include "lldb/Expression/UserExpression.h"
 #include "lldb/Host/Host.h"
 #include "lldb/Symbol/Block.h"
SBValueList SBFrame::GetVariables(const lldb::SBVariablesOptions &options) {
 
   std::set<VariableSP> variable_set;
   Process *process = exe_ctx.GetProcessPtr();
   if (target && process) {
     Process::StopLocker stop_locker;
     if (stop_locker.TryLock(&process->GetRunLock())) {
       frame = exe_ctx.GetFramePtr();
       if (frame) {
+        Debugger &dbg = process->GetTarget().GetDebugger();
         VariableList *variable_list = nullptr;
         Status var_error;
         variable_list = frame->GetVariableList(true, &var_error);
         if (var_error.Fail())
           value_list.SetError(var_error);
         if (variable_list) {
           const size_t num_variables = variable_list->GetSize();
           if (num_variables) {
             for (const VariableSP &variable_sp : *variable_list) {
+              if (dbg.InterruptRequested()) {
+                Log *log = GetLog(LLDBLog::Host);
+                LLDB_LOG(log, "Interrupted SBFrame::GetVariables");
+                return {};
+              }
               if (variable_sp) {
                 bool add_variable = false;
                 switch (variable_sp->GetScope()) {
                 case eValueTypeVariableGlobal:
                 case eValueTypeVariableStatic:
                 case eValueTypeVariableThreadLocal:
                   add_variable = statics;
                   break;

lldb/source/Commands/CommandObjectTarget.cpp

if (command.GetArgumentCount() == 0) {
       if (num_modules > 0) {
         result.GetOutputStream().Format(
             "Dumping symbol table for {0} modules.\n", num_modules);
         for (ModuleSP module_sp : module_list.ModulesNoLocking()) {
           if (num_dumped > 0) {
             result.GetOutputStream().EOL();
             result.GetOutputStream().EOL();
           }
-          if (m_interpreter.WasInterrupted())
+          if (GetDebugger().InterruptRequested())
             break;
           num_dumped++;
           DumpModuleSymtab(m_interpreter, result.GetOutputStream(),
                            module_sp.get(), m_options.m_sort_order,
                            name_preference);
         }
       } else {
         result.AppendError("the target has no associated executable images");
if (command.GetArgumentCount() == 0) {
             FindModulesByName(target, arg_cstr, module_list, true);
         if (num_matches > 0) {
           for (ModuleSP module_sp : module_list.Modules()) {
             if (module_sp) {
               if (num_dumped > 0) {
                 result.GetOutputStream().EOL();
                 result.GetOutputStream().EOL();
               }
-              if (m_interpreter.WasInterrupted())
+              if (GetDebugger().InterruptRequested())
                 break;
               num_dumped++;
               DumpModuleSymtab(m_interpreter, result.GetOutputStream(),
                                module_sp.get(), m_options.m_sort_order,
                                name_preference);
             }
           }
         } else
if (command.GetArgumentCount() == 0) {
       if (num_modules == 0) {
         result.AppendError("the target has no associated executable images");
         return false;
       }
 
       result.GetOutputStream().Format("Dumping sections for {0} modules.\n",
                                       num_modules);
       for (size_t image_idx = 0; image_idx < num_modules; ++image_idx) {
-        if (m_interpreter.WasInterrupted())
+        if (GetDebugger().InterruptRequested())
           break;
         num_dumped++;
         DumpModuleSections(
             m_interpreter, result.GetOutputStream(),
             target->GetImages().GetModulePointerAtIndex(image_idx));
       }
     } else {
       // Dump specified images (by basename or fullpath)
       const char *arg_cstr;
       for (int arg_idx = 0;
            (arg_cstr = command.GetArgumentAtIndex(arg_idx)) != nullptr;
            ++arg_idx) {
         ModuleList module_list;
         const size_t num_matches =
             FindModulesByName(target, arg_cstr, module_list, true);
         if (num_matches > 0) {
           for (size_t i = 0; i < num_matches; ++i) {
-            if (m_interpreter.WasInterrupted())
+            if (GetDebugger().InterruptRequested())
               break;
             Module *module = module_list.GetModulePointerAtIndex(i);
             if (module) {
               num_dumped++;
               DumpModuleSections(m_interpreter, result.GetOutputStream(),
                                  module);
             }
           }
if (num_modules == 0) {
       return false;
     }
 
     if (command.GetArgumentCount() == 0) {
       // Dump all ASTs for all modules images
       result.GetOutputStream().Format("Dumping clang ast for {0} modules.\n",
                                       num_modules);
       for (ModuleSP module_sp : module_list.ModulesNoLocking()) {
-        if (m_interpreter.WasInterrupted())
+        if (GetDebugger().InterruptRequested())
           break;
         if (SymbolFile *sf = module_sp->GetSymbolFile())
           sf->DumpClangAST(result.GetOutputStream());
       }
       result.SetStatus(eReturnStatusSuccessFinishResult);
       return true;
     }
 
     // Dump specified ASTs (by basename or fullpath)
     for (const Args::ArgEntry &arg : command.entries()) {
       ModuleList module_list;
       const size_t num_matches =
           FindModulesByName(target, arg.c_str(), module_list, true);
       if (num_matches == 0) {
         // Check the global list
         std::lock_guard<std::recursive_mutex> guard(
             Module::GetAllocationModuleCollectionMutex());
 
         result.AppendWarningWithFormat(
             "Unable to find an image that matches '%s'.\n", arg.c_str());
         continue;
       }
 
       for (size_t i = 0; i < num_matches; ++i) {
-        if (m_interpreter.WasInterrupted())
+        if (GetDebugger().InterruptRequested())
           break;
         Module *m = module_list.GetModulePointerAtIndex(i);
         if (SymbolFile *sf = m->GetSymbolFile())
           sf->DumpClangAST(result.GetOutputStream());
       }
     }
     result.SetStatus(eReturnStatusSuccessFinishResult);
     return true;
if (command.GetArgumentCount() == 0) {
       const size_t num_modules = target_modules.GetSize();
       if (num_modules == 0) {
         result.AppendError("the target has no associated executable images");
         return false;
       }
       result.GetOutputStream().Format(
           "Dumping debug symbols for {0} modules.\n", num_modules);
       for (ModuleSP module_sp : target_modules.ModulesNoLocking()) {
-        if (m_interpreter.WasInterrupted())
+        if (GetDebugger().InterruptRequested())
           break;
         if (DumpModuleSymbolFile(result.GetOutputStream(), module_sp.get()))
           num_dumped++;
       }
     } else {
       // Dump specified images (by basename or fullpath)
       const char *arg_cstr;
       for (int arg_idx = 0;
            (arg_cstr = command.GetArgumentAtIndex(arg_idx)) != nullptr;
            ++arg_idx) {
         ModuleList module_list;
         const size_t num_matches =
             FindModulesByName(target, arg_cstr, module_list, true);
         if (num_matches > 0) {
           for (size_t i = 0; i < num_matches; ++i) {
-            if (m_interpreter.WasInterrupted())
+            if (GetDebugger().InterruptRequested())
               break;
             Module *module = module_list.GetModulePointerAtIndex(i);
             if (module) {
               if (DumpModuleSymbolFile(result.GetOutputStream(), module))
                 num_dumped++;
             }
           }
         } else
if (command.GetArgumentCount() == 0) {
            ++arg_idx) {
         FileSpec file_spec(arg_cstr);
 
         const ModuleList &target_modules = target->GetImages();
         std::lock_guard<std::recursive_mutex> guard(target_modules.GetMutex());
         if (target_modules.GetSize() > 0) {
           uint32_t num_dumped = 0;
           for (ModuleSP module_sp : target_modules.ModulesNoLocking()) {
-            if (m_interpreter.WasInterrupted())
+            if (GetDebugger().InterruptRequested())
               break;
             if (DumpCompileUnitLineTable(
                     m_interpreter, result.GetOutputStream(), module_sp.get(),
                     file_spec,
                     m_options.m_verbose ? eDescriptionLevelFull
                                         : eDescriptionLevelBrief))
               num_dumped++;
           }

lldb/source/Commands/CommandObjectThread.cpp

bool HandleOneThread(lldb::tid_t tid, CommandReturnObject &result) override {
     const bool stop_format = true;
     if (!thread->GetStatus(strm, m_options.m_start, m_options.m_count,
                            num_frames_with_source, stop_format, only_stacks)) {
       result.AppendErrorWithFormat(
           "error displaying backtrace for thread: \"0x%4.4x\"\n",
           thread->GetIndexID());
       return false;
     }
-    if (m_options.m_extended_backtrace) {
+    if (m_options.m_extended_backtrace && !GetDebugger().InterruptRequested()) {
       DoExtendedBacktrace(thread, result);
     }
 
     return true;
   }
 
   CommandOptions m_options;
 };

lldb/source/Core/Debugger.cpp

 StreamSP Debugger::GetAsyncOutputStream() {
   return std::make_shared<StreamAsynchronousIO>(*this, true, GetUseColor());
 }
 
 StreamSP Debugger::GetAsyncErrorStream() {
   return std::make_shared<StreamAsynchronousIO>(*this, false, GetUseColor());
 }
 
+void Debugger::RequestInterrupt() {
+  std::lock_guard<std::mutex> guard(m_interrupt_mutex);
+  m_interrupt_requested++;
+}
+
+void Debugger::CancelInterruptRequest() {
+  std::lock_guard<std::mutex> guard(m_interrupt_mutex);
+  if (m_interrupt_requested > 0)
+    m_interrupt_requested--;
+}
+
+bool Debugger::InterruptRequested() {
+  // This is the one we should call internally.  This will return true either
+  // if there's a debugger interrupt and we aren't on the IOHandler thread, 
+  // or if we are on the IOHandler thread and there's a CommandInterpreter
+  // interrupt.
+  if (!IsIOHandlerThreadCurrentThread()) {
+    std::lock_guard<std::mutex> guard(m_interrupt_mutex);
+    return m_interrupt_requested != 0;
+  }
+  return GetCommandInterpreter().WasInterrupted();
+}
+
 size_t Debugger::GetNumDebuggers() {
   if (g_debugger_list_ptr && g_debugger_list_mutex_ptr) {
     std::lock_guard<std::recursive_mutex> guard(*g_debugger_list_mutex_ptr);
     return g_debugger_list_ptr->size();
   }
   return 0;
 }
 
void Debugger::HandleDiagnosticEvent(const lldb::EventSP &event_sp) {
   auto *data = DiagnosticEventData::GetEventDataFromEvent(event_sp.get());
   if (!data)
     return;
 
   StreamSP stream = GetAsyncErrorStream();
   data->Dump(stream.get());
 }
 
-bool Debugger::HasIOHandlerThread() { return m_io_handler_thread.IsJoinable(); }
+bool Debugger::HasIOHandlerThread() const {
+  return m_io_handler_thread.IsJoinable(); 
+}
+
+HostThread Debugger::SetIOHandlerThread(HostThread &new_thread) {
+  HostThread old_host = m_io_handler_thread;
+  m_io_handler_thread = new_thread;
+  return old_host;
+}
 
 bool Debugger::StartIOHandlerThread() {
   if (!m_io_handler_thread.IsJoinable()) {
     llvm::Expected<HostThread> io_handler_thread = ThreadLauncher::LaunchThread(
         "lldb.debugger.io-handler", [this] { return IOHandlerThread(); },
         8 * 1024 * 1024); // Use larger 8MB stack for this thread
     if (io_handler_thread) {
       m_io_handler_thread = *io_handler_thread;

 void Debugger::JoinIOHandlerThread() {
   if (HasIOHandlerThread()) {
     thread_result_t result;
     m_io_handler_thread.Join(&result);
     m_io_handler_thread = LLDB_INVALID_HOST_THREAD;
   }
 }
 
+bool Debugger::IsIOHandlerThreadCurrentThread() const {
+  if (!HasIOHandlerThread())
+    return false;
+  return m_io_handler_thread.EqualsThread(Host::GetCurrentThread());
+}
+
 Target &Debugger::GetSelectedOrDummyTarget(bool prefer_dummy) {
   if (!prefer_dummy) {
     if (TargetSP target = m_target_list.GetSelectedTarget())
       return *target;
   }
   return GetDummyTarget();
 }
 

lldb/source/Interpreter/CommandInterpreter.cpp

bool CommandInterpreter::HandleCommand(const char *command_line,
 
   Log *log = GetLog(LLDBLog::Commands);
   llvm::PrettyStackTraceFormat stack_trace("HandleCommand(command = \"%s\")",
                                    command_line);
 
   LLDB_LOGF(log, "Processing command: %s", command_line);
   LLDB_SCOPED_TIMERF("Processing command: %s.", command_line);
 
-  if (WasInterrupted()) {
-    result.AppendError("interrupted");
+  if (GetDebugger().InterruptRequested()) {
+    result.AppendError("... Interrupted");
     return false;
   }
 
   bool add_to_history;
   if (lazy_add_to_history == eLazyBoolCalculate)
     add_to_history = (m_command_source_depth == 0);
   else
     add_to_history = (lazy_add_to_history == eLazyBoolYes);
void CommandInterpreter::HandleCommands(const StringList &commands,
   // from the function.
 
   bool old_async_execution = m_debugger.GetAsyncExecution();
 
   if (!options.GetStopOnContinue()) {
     m_debugger.SetAsyncExecution(false);
   }
 
-  for (size_t idx = 0; idx < num_lines && !WasInterrupted(); idx++) {
+  for (size_t idx = 0; idx < num_lines; idx++) {
     const char *cmd = commands.GetStringAtIndex(idx);
     if (cmd[0] == '\0')
       continue;
 
     if (options.GetEchoCommands()) {
       // TODO: Add Stream support.
       result.AppendMessageWithFormat("%s %s\n",
                                      m_debugger.GetPrompt().str().c_str(), cmd);

 
 bool CommandInterpreter::InterruptCommand() {
   auto in_progress = CommandHandlingState::eInProgress;
   return m_command_state.compare_exchange_strong(
       in_progress, CommandHandlingState::eInterrupted);
 }
 
 bool CommandInterpreter::WasInterrupted() const {
+  if (!m_debugger.IsIOHandlerThreadCurrentThread())
+    return false;
+
   bool was_interrupted =
       (m_command_state == CommandHandlingState::eInterrupted);
   lldbassert(!was_interrupted || m_iohandler_nesting_level > 0);
   return was_interrupted;
 }
 
 void CommandInterpreter::PrintCommandOutput(IOHandler &io_handler,
                                             llvm::StringRef str,
                                             bool is_stdout) {
 
   lldb::StreamFileSP stream = is_stdout ? io_handler.GetOutputStreamFileSP()
                                         : io_handler.GetErrorStreamFileSP();
   // Split the output into lines and poll for interrupt requests
-  while (!str.empty() && !WasInterrupted()) {
+  bool had_output = !str.empty();
+  while (!str.empty()) {
     llvm::StringRef line;
     std::tie(line, str) = str.split('\n');
     {
       std::lock_guard<std::recursive_mutex> guard(io_handler.GetOutputMutex());
       stream->Write(line.data(), line.size());
       stream->Write("\n", 1);
     }
   }
 
   std::lock_guard<std::recursive_mutex> guard(io_handler.GetOutputMutex());
-  if (!str.empty())
+  if (had_output && GetDebugger().InterruptRequested())
     stream->Printf("\n... Interrupted.\n");
   stream->Flush();
 }
 
 bool CommandInterpreter::EchoCommandNonInteractive(
     llvm::StringRef line, const Flags &io_handler_flags) const {
   if (!io_handler_flags.Test(eHandleCommandFlagEchoCommand))
     return false;
CommandInterpreterRunResult CommandInterpreter::RunCommandInterpreter(
   m_result = CommandInterpreterRunResult();
 
   if (options.GetAutoHandleEvents())
     m_debugger.StartEventHandlerThread();
 
   if (options.GetSpawnThread()) {
     m_debugger.StartIOHandlerThread();
   } else {
+    // If the current thread is not managed by a host thread, we won't detect
+    // that this IS the CommandInterpreter IOHandler thread, so make it so:
+    HostThread new_io_handler_thread(Host::GetCurrentThread());
+    HostThread old_io_handler_thread 
+        = m_debugger.SetIOHandlerThread(new_io_handler_thread);
     m_debugger.RunIOHandlers();
+    m_debugger.SetIOHandlerThread(old_io_handler_thread);
 
     if (options.GetAutoHandleEvents())
       m_debugger.StopEventHandlerThread();
   }
 
   return m_result;
 }
 

lldb/source/Target/StackFrameList.cpp

 //===-- StackFrameList.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/StackFrameList.h"
 #include "lldb/Breakpoint/Breakpoint.h"
 #include "lldb/Breakpoint/BreakpointLocation.h"
+#include "lldb/Core/Debugger.h"
 #include "lldb/Core/SourceManager.h"
 #include "lldb/Core/StreamFile.h"
 #include "lldb/Symbol/Block.h"
 #include "lldb/Symbol/Function.h"
 #include "lldb/Symbol/Symbol.h"
 #include "lldb/Target/Process.h"
 #include "lldb/Target/RegisterContext.h"
 #include "lldb/Target/StackFrame.h"
if (end_idx > 0 && end_idx != UINT32_MAX) {
     inlined_depth = GetCurrentInlinedDepth();
     if (inlined_depth != UINT32_MAX) {
       if (end_idx > 0)
         end_idx += inlined_depth;
     }
   }
 
   StackFrameSP unwind_frame_sp;
+  Debugger &dbg = m_thread.GetProcess()->GetTarget().GetDebugger();
   do {
+    // Check for interruption here when building the frames - this is the
+    // expensive part, Dump later on is cheap.
+    if (dbg.InterruptRequested()) {
+      Log *log = GetLog(LLDBLog::Host);
+      LLDB_LOG(log, "Interrupted %s", __FUNCTION__);
+      break;
+    }
     uint32_t idx = m_concrete_frames_fetched++;
     lldb::addr_t pc = LLDB_INVALID_ADDRESS;
     lldb::addr_t cfa = LLDB_INVALID_ADDRESS;
     bool behaves_like_zeroth_frame = (idx == 0);
     if (idx == 0) {
       // We might have already created frame zero, only create it if we need
       // to.
       if (m_frames.empty()) {

lldb/test/API/python_api/was_interrupted/Makefile

+C_SOURCES := main.c
+CFLAGS_EXTRAS := -std=c99
+
+include Makefile.rules

lldb/test/API/python_api/was_interrupted/TestDebuggerInterruption.py

+"""
+Test SBDebugger.InterruptRequested and SBCommandInterpreter.WasInterrupted.
+"""
+
+import lldb
+import lldbsuite.test.lldbutil as lldbutil
+from lldbsuite.test.lldbtest import *
+import threading
+import os
+
+class TestDebuggerInterruption(TestBase):
+    """This test runs a command that starts up, rendevous with the test thread
+       using threading barriers, then checks whether it has been interrupted.
+
+    The command's first argument is either 'interp' or 'debugger', to test
+    InterruptRequested and WasInterrupted respectively.
+
+    The command has two modes, interrupt and check, the former is the one that
+    waits for an interrupt.  Then latter just returns whether an interrupt was
+    requested.  We use the latter to make sure we took down the flag correctly."""
+
+    NO_DEBUG_INFO_TESTCASE = True
+
+    class CommandRunner(threading.Thread):
+        """This class is for running a command, and for making a thread to run the command on.
+           It gets passed the test it is working on behalf of, and most of the important
+           objects come from the test. """
+        def __init__(self, test):
+            super().__init__()
+            self.test = test
+
+        def rendevous(self):
+            # We smuggle out barriers and event to the runner thread using thread local data:
+            import interruptible
+            interruptible.local_data = interruptible.BarrierContainer(self.test.before_interrupt_barrier,
+                                                                   self.test.after_interrupt_barrier,
+                                                                   self.test.event)
+            
+    class DirectCommandRunner(CommandRunner):
+        """"This version runs a single command using HandleCommand."""
+        def __init__(self, test, command):
+            super().__init__(test)
+            self.command = command
+        
+        def run(self):
+            self.rendevous()
+            result = self.test.dbg.GetCommandInterpreter().HandleCommand(self.command, self.test.result)
+            if self.test.result_barrier:
+                self.test.result_barrier.wait()
+
+    class CommandInterpreterRunner(CommandRunner):
+        """This version runs the CommandInterpreter and feeds the command to it."""
+        def __init__(self, test):
+            super().__init__(test)
+
+        def run(self):
+            self.rendevous()
+
+            test = self.test
+            
+            # We will use files for debugger input and output:
+            
+            # First write down the command:
+            with open(test.getBuildArtifact(test.in_filename), "w") as f:
+                f.write(f"{test.command}\n")
+
+            # Now set the debugger's stdout & stdin to our files, and run
+            # the CommandInterpreter:
+            with open(test.out_filename, "w") as outf, open(test.in_filename, "r") as inf:
+                outsbf = lldb.SBFile(outf.fileno(), "w", False)
+                orig_outf = test.dbg.GetOutputFile()
+                error = test.dbg.SetOutputFile(outsbf)
+                test.assertSuccess(error, "Could not set outfile")
+
+                insbf = lldb.SBFile(inf.fileno(), "r", False)
+                orig_inf = test.dbg.GetOutputFile()
+                error = test.dbg.SetInputFile(insbf)
+                test.assertSuccess(error, "Could not set infile")
+                      
+                options = lldb.SBCommandInterpreterRunOptions()
+                options.SetPrintResults(True)
+                options.SetEchoCommands(False)
+                
+                test.dbg.RunCommandInterpreter(True, False, options, 0, False, False)
+                test.dbg.GetOutputFile().Flush()
+
+                error = test.dbg.SetOutputFile(orig_outf)
+                test.assertSuccess(error, "Restored outfile")
+                test.dbg.SetInputFile(orig_inf)
+                test.assertSuccess(error, "Restored infile")
+            
+    def command_setup(self, args):
+        """Insert our command, if needed.  Then set up event and barriers if needed.
+           Then return the command to run."""
+
+        self.interp = self.dbg.GetCommandInterpreter()
+        self.command_name = "interruptible_command"
+        self.cmd_result = lldb.SBCommandReturnObject()
+
+        if not "check" in args:
+            self.event = threading.Event()
+            self.result_barrier = threading.Barrier(2, timeout=10)
+            self.before_interrupt_barrier = threading.Barrier(2, timeout=10)
+            self.after_interrupt_barrier = threading.Barrier(2, timeout=10)
+        else:
+            self.event = None
+            self.result_barrier = None
+            self.before_interrupt_barrier = None
+            self.after_interrupt_barrier = None
+
+        if not self.interp.UserCommandExists(self.command_name):
+            # Make the command we're going to use - it spins calling WasInterrupted:
+            cmd_filename = "interruptible"
+            cmd_filename = os.path.join(self.getSourceDir(), "interruptible.py")
+            self.runCmd(f"command script import {cmd_filename}")
+            cmd_string = f"command script add {self.command_name} --class interruptible.WelcomeCommand"
+            self.runCmd(cmd_string)
+
+        if len(args) == 0:
+            command = self.command_name
+        else:
+            command = self.command_name + " " + args
+        return command
+    
+    def run_single_command(self, command):
+        # Now start up a thread to run the command:
+        self.result.Clear()
+        self.runner = TestDebuggerInterruption.DirectCommandRunner(self, command)
+        self.runner.start()
+
+    def start_command_interp(self):
+        self.runner = TestDebuggerInterruption.CommandInterpreterRunner(self)
+        self.runner.start()
+        
+    def check_text(self, result_text, interrupted):
+        if interrupted: 
+            self.assertIn("Command was interrupted", result_text,
+                          "Got the interrupted message")
+        else:
+            self.assertIn("Command was not interrupted", result_text,
+                          "Got the not interrupted message")
+        
+    def gather_output(self):
+        # Now wait for the interrupt to interrupt the command:
+        self.runner.join(10.0)
+        finished = not self.runner.is_alive()
+        # Don't leave the runner thread stranded if the interrupt didn't work.
+        if not finished:
+            self.event.set()
+            self.runner.join(10.0)
+
+        self.assertTrue(finished, "We did finish the command")
+        
+    def check_result(self, interrupted = True):
+        self.gather_output()
+        self.check_text(self.result.GetOutput(), interrupted)
+
+    def check_result_output(self, interrupted = True):
+        self.gather_output()
+        buffer = ""
+        # Okay, now open the file for reading, and read.
+        with open(self.out_filename, "r") as f:
+            buffer = f.read()
+
+        self.assertNotEqual(len(buffer), 0, "No command data")
+        self.check_text(buffer, interrupted)
+        
+    def debugger_interrupt_test(self, use_interrupt_requested):
+        """Test that debugger interruption interrupts a command
+           running directly through HandleCommand.
+           If use_interrupt_requested is true, we'll check that API,
+           otherwise we'll check WasInterrupted.  They should both do
+           the same thing."""
+
+        if use_interrupt_requested:
+            command = self.command_setup("debugger")
+        else:
+            command = self.command_setup("interp")
+
+        self.result = lldb.SBCommandReturnObject()
+        self.run_single_command(command)
+
+        # Okay now wait till the command has gotten started to issue the interrupt:
+        self.before_interrupt_barrier.wait()
+        # I'm going to do it twice here to test that it works as a counter:
+        self.dbg.RequestInterrupt()
+        self.dbg.RequestInterrupt()
+        
+        def cleanup():
+            self.dbg.CancelInterruptRequest()
+        self.addTearDownHook(cleanup)
+        # Okay, now set both sides going:
+        self.after_interrupt_barrier.wait()
+        
+        # Check that the command was indeed interrupted.  First rendevous
+        # after the runner thread had a chance to execute the command:
+        self.result_barrier.wait()
+        self.assertTrue(self.result.Succeeded(), "Our command succeeded")
+        result_output = self.result.GetOutput()
+        self.check_result(True)
+
+        # Do it again to make sure that the counter is counting:
+        self.dbg.CancelInterruptRequest()
+        command = self.command_setup("debugger")
+        self.run_single_command(command)
+
+        # This time we won't even get to run the command, since HandleCommand
+        # checks for the interrupt state on entry, so we don't wait on the command
+        # barriers.
+        self.result_barrier.wait()
+        
+        # Again check that we were
+        self.assertFalse(self.result.Succeeded(), "Our command was not allowed to run")
+        error_output = self.result.GetError()
+        self.assertIn("... Interrupted", error_output, "Command was cut short by interrupt")
+        
+        # Now take down the flag, and make sure that we aren't interrupted:
+        self.dbg.CancelInterruptRequest()
+
+        # Now make sure that we really did take down the flag:
+        command = self.command_setup("debugger check")
+        self.run_single_command(command)
+        result_output = self.result.GetOutput()
+        self.check_result(False)
+
+    def test_debugger_interrupt_use_dbg(self):
+        self.debugger_interrupt_test(True)
+        
+    def test_debugger_interrupt_use_interp(self):
+        self.debugger_interrupt_test(False)
+        
+    def test_interp_doesnt_interrupt_debugger(self):
+        """Test that interpreter interruption does not interrupt a command
+           running directly through HandleCommand.
+           If use_interrupt_requested is true, we'll check that API,
+           otherwise we'll check WasInterrupted.  They should both do
+           the same thing."""
+
+        command = self.command_setup("debugger poll")
+
+        self.result = lldb.SBCommandReturnObject()
+        self.run_single_command(command)
+
+        # Now raise the debugger interrupt flag.  It will also interrupt the command:
+        self.before_interrupt_barrier.wait()
+        self.dbg.GetCommandInterpreter().InterruptCommand()
+        self.after_interrupt_barrier.wait()
+        
+        # Check that the command was indeed interrupted:
+        self.result_barrier.wait()
+        self.assertTrue(self.result.Succeeded(), "Our command succeeded")
+        result_output = self.result.GetOutput()
+        self.check_result(False)
+
+
+    def interruptible_command_test(self, use_interrupt_requested):
+        """Test that interpreter interruption interrupts a command
+           running in the RunCommandInterpreter loop.
+           If use_interrupt_requested is true, we'll check that API,
+           otherwise we'll check WasInterrupted.  They should both do
+           the same thing."""
+        
+        self.out_filename = self.getBuildArtifact("output")
+        self.in_filename = self.getBuildArtifact("input")
+        # We're going to overwrite the input file, but we
+        # don't want data accumulating in the output file.
+
+        if os.path.exists(self.out_filename):
+            os.unlink(self.out_filename)
+
+        # You should be able to use either check method interchangeably:
+        if use_interrupt_requested:
+            self.command = self.command_setup("debugger") + "\n"
+        else:
+            self.command = self.command_setup("interp") + "\n"
+
+        self.start_command_interp()
+
+        # Now give the interpreter a chance to run this command up
+        # to the first barrier
+        self.before_interrupt_barrier.wait()
+        # Then issue the interrupt:
+        sent_interrupt = self.dbg.GetCommandInterpreter().InterruptCommand()
+        self.assertTrue(sent_interrupt, "Did send command interrupt.")
+        # Now give the command a chance to finish:
+        self.after_interrupt_barrier.wait()
+        
+        self.check_result_output(True)
+
+        os.unlink(self.out_filename)
+
+        # Now send the check command, and make sure the flag is now down.
+        self.command = self.command_setup("interp check") + "\n"
+        self.start_command_interp()
+        
+        self.check_result_output(False)
+
+    def test_interruptible_command_check_dbg(self):
+        self.interruptible_command_test(True)
+        
+    def test_interruptible_command_check_interp(self):
+        self.interruptible_command_test(False)
+
+    def test_debugger_doesnt_interrupt_command(self):
+        """Test that debugger interruption doesn't interrupt a command
+           running in the RunCommandInterpreter loop."""
+        
+        self.out_filename = self.getBuildArtifact("output")
+        self.in_filename = self.getBuildArtifact("input")
+        # We're going to overwrite the input file, but we
+        # don't want data accumulating in the output file.
+
+        if os.path.exists(self.out_filename):
+            os.unlink(self.out_filename)
+
+        self.command = self.command_setup("interp poll") + "\n"
+
+        self.start_command_interp()
+
+        self.before_interrupt_barrier.wait()
+        self.dbg.RequestInterrupt()
+        def cleanup():
+            self.dbg.CancelInterruptRequest()
+        self.addTearDownHook(cleanup)
+        self.after_interrupt_barrier.wait()
+
+        self.check_result_output(False)
+
+        os.unlink(self.out_filename)
+

lldb/test/API/python_api/was_interrupted/interruptible.py

+import lldb
+import threading
+
+local_data = None
+
+class BarrierContainer(threading.local):
+    def __init__(self, before_interrupt_barrier, after_interrupt_barrier,  event):
+        self.event = event
+        self.before_interrupt_barrier = before_interrupt_barrier
+        self.after_interrupt_barrier = after_interrupt_barrier
+
+class WelcomeCommand(object):
+
+    def __init__(self, debugger, session_dict):
+        return
+
+    def get_short_help(self):
+        return "A command that waits for an interrupt before returning."
+
+    def check_was_interrupted(self, debugger, use_interpreter):
+        if use_interpreter:
+            self.was_interrupted = debugger.GetCommandInterpreter().WasInterrupted()
+        else:
+            self.was_interrupted = debugger.InterruptRequested()
+        if local_data.event:
+            self.was_canceled = local_data.event.is_set()
+
+    def __call__(self, debugger, args, exe_ctx, result):
+        """Command arguments:
+            {interp/debugger} - Whether to use SBCommandInterpreter::WasInterrupted
+                                of SBDebugger::InterruptRequested().
+            check - Don't do the rendevous, just check if an interrupt was requested.
+                    If check is not provided, we'll do the lock and then check.
+            poll  - Should we poll once after the rendevous or spin waiting for the
+                    interruption to happen.
+
+            For the interrupt cases, the command waits serially on the barriers
+            passed to it in local data, giving the test runner a chance to set the
+            interrupt.  Once the barriers are passed, it waits for the interrupt
+            or the event.
+            If it finds an interrupt, it returns "Command was interrupted". If it gets an
+            event before seeing the interrupt it returns "Command was not interrupted."
+            For the "poll" case, it waits on the rendevous, then checks once.
+            For the "check" case, it doesn't wait, but just returns whether there was
+            an interrupt in force or not."""
+            
+        if local_data == None:
+            result.SetError("local data was not set.")
+            result.SetStatus(lldb.eReturnStatusFailed)
+            return
+
+        use_interpreter = "interp" in args
+        if not use_interpreter:
+            if not "debugger" in args:
+                result.SetError("Must pass either 'interp' or 'debugger'")
+                result.SetStatus(lldb.eReturnStatusFailed)
+                return
+            
+        self.was_interrupted = False
+        self.was_canceled = False
+        
+        if "check" in args:
+            self.check_was_interrupted(debugger, use_interpreter)
+            if self.was_interrupted:
+                result.Print("Command was interrupted")
+            else:
+                result.Print("Command was not interrupted")
+        else:
+            # Wait here to rendevous in the test before it sets the interrupt.
+            local_data.before_interrupt_barrier.wait()
+            # Now the test will set the interrupt, and we can continue:
+            local_data.after_interrupt_barrier.wait()
+            
+            if "poll" in args:
+                self.check_was_interrupted(debugger, use_interpreter)
+            else:
+                while not self.was_interrupted and not self.was_canceled:
+                    self.check_was_interrupted(debugger, use_interpreter)
+
+            if self.was_interrupted:
+                result.Print("Command was interrupted")
+            else:
+                result.Print("Command was not interrupted")
+
+            if self.was_canceled:
+                result.Print("Command was canceled")
+        result.SetStatus(lldb.eReturnStatusSuccessFinishResult)
+        return True
+
+

lldb/test/API/python_api/was_interrupted/main.c

+#include <stdio.h>
+
+int global_test_var = 10;
+
+int
+main()
+{
+  int test_var = 10;
+  printf ("Set a breakpoint here: %d.\n", test_var);
+  return global_test_var;
+}