[lldb/lua] Support external breakpoint callback

[siger-young]

Summary

This commit supports registering breakpoint callback when using
liblldb in Lua. (able to SetScriptCallback(function(a, b, ...) end))

[siger-young]

Remove "return" to prevent memory leakage.

[labath]

I actually quite like this, but we should figure out a way to do it while respecting our SB contracts. See inline comments for details.

lldb/bindings/lua/lua-wrapper.swig

119–124

I have (just yesterday) reformatted these files to follow the normal llvm/lldb style. Could you please rebase and reformat the patch so we don't profilerate this weirdness.

lldb/include/lldb/API/SBBreakpointOptionCommon.h

15

The reason this file was in the source folder is because lldb public header cannot depend the internal ones. We'll need to figure out a different way to do that.

I guess that means placing these definitions somewhere where they would be accessible by the swig code, but still inaccessible to the outside world. Would any of the FileSP tricks we do in the python code help?

lldb/include/lldb/API/SBDefines.h

97–99

What's the reason for changing this?

If this were a new API, then I think I might agree with having an SBFrame here, but we'd need a very good reason to change this after the fact. I would assume the sb_frame object can be accessed as thread.GetFrameAtIndex(0), can it not?

[labath]

I don't know if you've seen this but we have some description of it here https://lldb.llvm.org/design/sbapi.html. The gist of it is:

• be backward compatible
• don't depend on other stuff

[siger-young]

In D115926#3199496, @labath wrote:

I don't know if you've seen this but we have some description of it here https://lldb.llvm.org/design/sbapi.html. The gist of it is:

• be backward compatible
• don't depend on other stuff

Thanks, I got it. I will stick to these rules.

[jingham]

In D115926#3199520, @siger-young wrote:

In D115926#3199496, @labath wrote:

I don't know if you've seen this but we have some description of it here https://lldb.llvm.org/design/sbapi.html. The gist of it is:

• be backward compatible
• don't depend on other stuff

Thanks, I got it. I will stick to these rules.

It's fine to add an API if we decide the one we had originally was unwieldily. I have no idea why one of us (probably me) thought breakpoint callbacks needed a process & thread. But since this is a typedef, you'd have to make a second name, which is probably too awkward.

lldb/include/lldb/API/SBBreakpointOptionCommon.h

17

It's odd to have something called lldb::CallbackData, but have it be specific to breakpoints. We probably need to do the same thing for Watchpoints, for instance, but either there should be a common class for both watchpoints, or they should be distinguishable by name. And other things might have callbacks.

lldb/bindings/interface/SBBreakpoint.i

public:
 
     void
     SetQueueName (const char *queue_name);
 
     const char *
     GetQueueName () const;
 
     %feature("docstring", "
+    Set a specific closure to be called when the breakpoint is hit.") SetScriptCallback;
+    void
+    SetScriptCallback (const SBBreakpointCallbackBatonSP &baton_sp);
+
+    %feature("docstring", "
     Set the name of the script function to be called when the breakpoint is hit.") SetScriptCallbackFunction;
     void
     SetScriptCallbackFunction (const char *callback_function_name);
 
     %feature("docstring", "
     Set the name of the script function to be called when the breakpoint is hit.
     To use this variant, the function should take (frame, bp_loc, extra_args, internal_dict) and
     when the breakpoint is hit the extra_args will be passed to the callback function.") SetScriptCallbackFunction;

lldb/bindings/lua/lua-typemaps.swig

if (lua_isnil(L, $input)) {
       $2 = 0;
    }
    else {
       $1 = (char *)luaL_checklstring(L, $input, (size_t *)&$2);
    }
 }
 
 //===----------------------------------------------------------------------===//
+
+// Typemap for closure callback in external scripting environment
+
+%typemap(arginit) const SBBreakpointCallbackBatonSP &baton_sp {
+   // We could `SBBreakpointCallbackBatonSP baton_sp;` inside "%typemap(in)"
+   // but SWIG puts "%typemap(in)" part and the real call in 2 *different* scopes
+   // so the smart pointer destructs earlier than it is used by the call.
+   $1 = new SBBreakpointCallbackBatonSP();
+}
+
+%typemap(in) const SBBreakpointCallbackBatonSP &baton_sp {
+   if (lua_isfunction(L, $input)) {
+      auto data_up = std::make_unique<CallbackDataLua>(L);
+      lua_pushlightuserdata(L, data_up.get());
+      lua_pushvalue(L, $input);
+      lua_settable(L, LUA_REGISTRYINDEX);
+      *$1 = std::make_shared<SBBreakpointCallbackBaton>(std::move(data_up));
+   }
+   else {
+      luaL_error(L, "Expect a Lua function.");
+   }
+}
+
+%typemap(freearg) const SBBreakpointCallbackBatonSP &baton_sp {
+   free($1);
+}

lldb/bindings/lua/lua-wrapper.swig

LLDBSwigLuaCallLuaLogOutputCallback(const char *str, void *baton) {
    lua_pushstring(L, str);
    lua_pcall(L, 1, 0, 0);
 }
 
 static int LLDBSwigLuaCloseFileHandle(lua_State *L) {
    return luaL_error(L, "You cannot close a file handle used by lldb.");
 }
 
+// These are external callback wrappers.
+
+bool SBBreakpointHitCallbackLua(
+   void *baton,
+   SBFrame &sb_frame,
+   SBBreakpointLocation &sb_bp_loc
+);
+
+struct CallbackDataLua : public CallbackData {
+public:
+   CallbackDataLua(lua_State *l) : L(l) {
+      callback = SBBreakpointHitCallbackLua;
+      callback_baton = (void *) this;
+   }
+   lua_State *L;
+};
+
+
+bool SBBreakpointHitCallbackLua(
+   void *baton,
+   SBFrame &sb_frame,
+   SBBreakpointLocation &sb_bp_loc
+)
+{
+   auto data = (CallbackDataLua *) baton;
+
+   lua_State *L = data->L;
+   lua_pushlightuserdata(L, data);
+   lua_gettable(L, LUA_REGISTRYINDEX);
+   int nargs = 2;
+
+   // Push the Lua wrappers
+   PushSBClass(L, &sb_frame);
+   PushSBClass(L, &sb_bp_loc);
+
+   // Call into the Lua callback passing 'sb_frame' and 'sb_wp'.
+   if (lua_pcall(L, nargs, 1, 0) != LUA_OK) {
+      luaL_error(L, "%s", lua_tostring(L, -1));
+      return true;
+   }
+
+   // Boolean return from the callback
+   bool stop = lua_toboolean(L, -1);
+   lua_pop(L, 1);
+
+   return stop;
+}
+
 %}

lldb/include/lldb/API/SBBreakpoint.h

 //===-- SBBreakpoint.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_API_SBBREAKPOINT_H
 #define LLDB_API_SBBREAKPOINT_H
 
+#include "lldb/API/SBBreakpointOptionCommon.h"
 #include "lldb/API/SBDefines.h"
 
 class SBBreakpointListImpl;
 
 namespace lldb {
 
 class LLDB_API SBBreakpoint {
 public:
public:
   const char *GetThreadName() const;
 
   void SetQueueName(const char *queue_name);
 
   const char *GetQueueName() const;
 
   void SetCallback(SBBreakpointHitCallback callback, void *baton);
 
+  void SetScriptCallback(const SBBreakpointCallbackBatonSP &baton_sp);
+
   void SetScriptCallbackFunction(const char *callback_function_name);
 
   SBError SetScriptCallbackFunction(const char *callback_function_name,
                                  SBStructuredData &extra_args);
 
   void SetCommandLineCommands(SBStringList &commands);
 
   bool GetCommandLineCommands(SBStringList &commands);

lldb/include/lldb/API/SBBreakpointOptionCommon.h

+//===-- SBBreakpointOptionCommon.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_API_SBBREAKPOINTOPTIONCOMMON_H
+#define LLDB_API_SBBREAKPOINTOPTIONCOMMON_H
+
+#include "lldb/API/SBDefines.h"
+#include "lldb/Utility/Baton.h"
+
+namespace lldb {
+struct CallbackData {
+  SBBreakpointHitCallback callback;
+  void *callback_baton;
+
+  virtual ~CallbackData() = default;
+};
+
+class SBBreakpointCallbackBaton
+    : public lldb_private::TypedBaton<CallbackData> {
+public:
+  explicit SBBreakpointCallbackBaton(std::unique_ptr<CallbackData> Data);
+  SBBreakpointCallbackBaton(SBBreakpointHitCallback callback, void *baton);
+
+  ~SBBreakpointCallbackBaton() override;
+
+  static bool PrivateBreakpointHitCallback(
+      void *baton, lldb_private::StoppointCallbackContext *ctx,
+      lldb::user_id_t break_id, lldb::user_id_t break_loc_id);
+};
+
+typedef std::shared_ptr<SBBreakpointCallbackBaton> SBBreakpointCallbackBatonSP;
+
+} // namespace lldb
+#endif // LLDB_API_SBBREAKPOINTOPTIONCOMMON_H

lldb/include/lldb/API/SBDefines.h

 class LLDB_API SBTypeSynthetic;
 class LLDB_API SBTypeList;
 class LLDB_API SBValue;
 class LLDB_API SBValueList;
 class LLDB_API SBVariablesOptions;
 class LLDB_API SBWatchpoint;
 class LLDB_API SBUnixSignals;
 
-typedef bool (*SBBreakpointHitCallback)(void *baton, SBProcess &process,
-                                        SBThread &thread,
-                                        lldb::SBBreakpointLocation &location);
+typedef bool (*SBBreakpointHitCallback)(void *baton, SBFrame &sb_frame,
+                                        SBBreakpointLocation &sb_bp_loc);
 }
 
 #endif // LLDB_API_SBDEFINES_H

lldb/source/API/SBBreakpoint.cpp

 //===-- SBBreakpoint.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/API/SBBreakpoint.h"
 #include "SBReproducerPrivate.h"
 #include "lldb/API/SBBreakpointLocation.h"
+#include "lldb/API/SBBreakpointOptionCommon.h"
 #include "lldb/API/SBDebugger.h"
 #include "lldb/API/SBEvent.h"
 #include "lldb/API/SBProcess.h"
 #include "lldb/API/SBStream.h"
 #include "lldb/API/SBStringList.h"
 #include "lldb/API/SBStructuredData.h"
 #include "lldb/API/SBThread.h"
 

 #include "lldb/Interpreter/ScriptInterpreter.h"
 #include "lldb/Target/Process.h"
 #include "lldb/Target/SectionLoadList.h"
 #include "lldb/Target/Target.h"
 #include "lldb/Target/Thread.h"
 #include "lldb/Target/ThreadSpec.h"
 #include "lldb/Utility/Stream.h"
 
-#include "SBBreakpointOptionCommon.h"
-
 #include "lldb/lldb-enumerations.h"
 
 #include "llvm/ADT/STLExtras.h"
 
 using namespace lldb;
 using namespace lldb_private;
 
 SBBreakpoint::SBBreakpoint() { LLDB_RECORD_CONSTRUCTOR_NO_ARGS(SBBreakpoint); }
std::lock_guard<std::recursive_mutex> guard(
         bkpt_sp->GetTarget().GetAPIMutex());
     BatonSP baton_sp(new SBBreakpointCallbackBaton(callback, baton));
     bkpt_sp->SetCallback(SBBreakpointCallbackBaton
       ::PrivateBreakpointHitCallback, baton_sp,
                          false);
   }
 }
 
+void SBBreakpoint::SetScriptCallback(const SBBreakpointCallbackBatonSP &baton_sp) {
+  LLDB_RECORD_METHOD(void, SBBreakpoint, SetScriptCallback,
+                     (const SBBreakpointCallbackBatonSP &), baton_sp);
+
+  BreakpointSP bkpt_sp = GetSP();
+
+  if (bkpt_sp) {
+    std::lock_guard<std::recursive_mutex> guard(
+        bkpt_sp->GetTarget().GetAPIMutex());
+    bkpt_sp->SetCallback(
+        SBBreakpointCallbackBaton ::PrivateBreakpointHitCallback, baton_sp,
+        false);
+  }
+}
+
 void SBBreakpoint::SetScriptCallbackFunction(
   const char *callback_function_name) {
 LLDB_RECORD_METHOD(void, SBBreakpoint, SetScriptCallbackFunction,
                    (const char *), callback_function_name);
   SBStructuredData empty_args;
   SetScriptCallbackFunction(callback_function_name, empty_args);
 }
 
void RegisterMethods<SBBreakpoint>(Registry &R) {
   LLDB_REGISTER_METHOD(bool, SBBreakpoint, GetDescription,
                        (lldb::SBStream &));
   LLDB_REGISTER_METHOD(bool, SBBreakpoint, GetDescription,
                        (lldb::SBStream &, bool));
   LLDB_REGISTER_METHOD(lldb::SBError, SBBreakpoint, AddLocation,
                        (lldb::SBAddress &));
   LLDB_REGISTER_METHOD(lldb::SBStructuredData, SBBreakpoint,
                        SerializeToStructuredData, ());
+  LLDB_REGISTER_METHOD(void, SBBreakpoint, SetScriptCallback,
+                       (const SBBreakpointCallbackBatonSP &));
   LLDB_REGISTER_METHOD(void, SBBreakpoint, SetScriptCallbackFunction,
                        (const char *));
   LLDB_REGISTER_METHOD(lldb::SBError, SBBreakpoint, SetScriptCallbackFunction,
                        (const char *, SBStructuredData &));
   LLDB_REGISTER_METHOD(lldb::SBError, SBBreakpoint, SetScriptCallbackBody,
                        (const char *));
   LLDB_REGISTER_METHOD(bool, SBBreakpoint, AddName, (const char *));
   LLDB_REGISTER_METHOD(lldb::SBError, SBBreakpoint, AddNameWithErrorHandling,

lldb/source/API/SBBreakpointName.cpp

 //===-- SBBreakpointName.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/API/SBBreakpointName.h"
 #include "SBReproducerPrivate.h"
+#include "lldb/API/SBBreakpointOptionCommon.h"
 #include "lldb/API/SBDebugger.h"
 #include "lldb/API/SBError.h"
 #include "lldb/API/SBStream.h"
 #include "lldb/API/SBStringList.h"
 #include "lldb/API/SBStructuredData.h"
 #include "lldb/API/SBTarget.h"
 
 #include "lldb/Breakpoint/BreakpointName.h"
 #include "lldb/Breakpoint/StoppointCallbackContext.h"
 #include "lldb/Core/Debugger.h"
 #include "lldb/Core/StructuredDataImpl.h"
 #include "lldb/Interpreter/CommandInterpreter.h"
 #include "lldb/Interpreter/ScriptInterpreter.h"
 #include "lldb/Target/Target.h"
 #include "lldb/Target/ThreadSpec.h"
 #include "lldb/Utility/Stream.h"
 
-#include "SBBreakpointOptionCommon.h"
-
 using namespace lldb;
 using namespace lldb_private;
 
 namespace lldb
 {
 class SBBreakpointNameImpl {
 public:
   SBBreakpointNameImpl(TargetSP target_sp, const char *name) {

lldb/source/API/SBBreakpointOptionCommon.h

-//===-- SBBreakpointOptionCommon.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_SOURCE_API_SBBREAKPOINTOPTIONCOMMON_H
-#define LLDB_SOURCE_API_SBBREAKPOINTOPTIONCOMMON_H
-
-#include "lldb/API/SBDefines.h"
-#include "lldb/Utility/Baton.h"
-
-namespace lldb
-{
-struct CallbackData {
-  SBBreakpointHitCallback callback;
-  void *callback_baton;
-};
-
-class SBBreakpointCallbackBaton : public lldb_private::TypedBaton<CallbackData> {
-public:
-  SBBreakpointCallbackBaton(SBBreakpointHitCallback callback,
-                            void *baton);
-
-  ~SBBreakpointCallbackBaton() override;
-
-  static bool PrivateBreakpointHitCallback(void *baton,
-                                           lldb_private::StoppointCallbackContext *ctx,
-                                           lldb::user_id_t break_id,
-                                           lldb::user_id_t break_loc_id);
-};
-
-} // namespace lldb
-#endif // LLDB_SOURCE_API_SBBREAKPOINTOPTIONCOMMON_H

lldb/source/API/SBBreakpointOptionCommon.cpp

 //===-- SBBreakpointOptionCommon.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/API/SBBreakpointName.h"
+#include "lldb/API/SBBreakpointOptionCommon.h"
 #include "lldb/API/SBBreakpointLocation.h"
+#include "lldb/API/SBBreakpointName.h"
 #include "lldb/API/SBDebugger.h"
 #include "lldb/API/SBEvent.h"
 #include "lldb/API/SBProcess.h"
 #include "lldb/API/SBStream.h"
 #include "lldb/API/SBStringList.h"
 #include "lldb/API/SBThread.h"
 
 #include "lldb/Breakpoint/BreakpointName.h"
 #include "lldb/Breakpoint/StoppointCallbackContext.h"
 #include "lldb/Core/Address.h"
 #include "lldb/Core/Debugger.h"
 #include "lldb/Core/StreamFile.h"
 #include "lldb/Interpreter/CommandInterpreter.h"
 #include "lldb/Interpreter/ScriptInterpreter.h"
 #include "lldb/Target/Process.h"
 #include "lldb/Target/Target.h"
 #include "lldb/Target/Thread.h"
 #include "lldb/Target/ThreadSpec.h"
 #include "lldb/Utility/Log.h"
 #include "lldb/Utility/Stream.h"
 
 #include "lldb/lldb-enumerations.h"
 
-#include "SBBreakpointOptionCommon.h"
-
 #include "llvm/ADT/STLExtras.h"
 
 using namespace lldb;
 using namespace lldb_private;
 
+SBBreakpointCallbackBaton::SBBreakpointCallbackBaton(
+    std::unique_ptr<CallbackData> Data)
+    : TypedBaton(std::move(Data)) {}
+
 SBBreakpointCallbackBaton::SBBreakpointCallbackBaton(SBBreakpointHitCallback 
                                                          callback,
                                                      void *baton)
       : TypedBaton(std::make_unique<CallbackData>()) {
     getItem()->callback = callback;
     getItem()->callback_baton = baton;
   }
 
  bool SBBreakpointCallbackBaton::PrivateBreakpointHitCallback(void *baton,
                                                   StoppointCallbackContext *ctx,
                                                   lldb::user_id_t break_id,
                                                   lldb::user_id_t break_loc_id)
 {
   ExecutionContext exe_ctx(ctx->exe_ctx_ref);
+  SBFrame sb_frame(exe_ctx.GetFrameSP());
   BreakpointSP bp_sp(
       exe_ctx.GetTargetRef().GetBreakpointList().FindBreakpointByID(break_id));
   if (baton && bp_sp) {
     CallbackData *data = (CallbackData *)baton;
     lldb_private::Breakpoint *bp = bp_sp.get();
+
     if (bp && data->callback) {
-      Process *process = exe_ctx.GetProcessPtr();
-      if (process) {
-        SBProcess sb_process(process->shared_from_this());
-        SBThread sb_thread;
-        SBBreakpointLocation sb_location;
-        assert(bp_sp);
-        sb_location.SetLocation(bp_sp->FindLocationByID(break_loc_id));
-        Thread *thread = exe_ctx.GetThreadPtr();
-        if (thread)
-          sb_thread.SetThread(thread->shared_from_this());
-
-        return data->callback(data->callback_baton, sb_process, sb_thread,
-                              sb_location);
-      }
+      SBBreakpointLocation sb_bp_loc;
+      sb_bp_loc.SetLocation(bp_sp->FindLocationByID(break_loc_id));
+      return data->callback(data->callback_baton, sb_frame, sb_bp_loc);
     }
   }
   return true; // Return true if we should stop at this breakpoint
 }
 
 SBBreakpointCallbackBaton::~SBBreakpointCallbackBaton() = default;

lldb/test/API/lua_api/TestBreakpointAPI.lua

function _T:TestBreakpointFrame()
     assertTrue(frame:IsValid())
     local error = lldb.SBError()
     local var_argc = frame:FindVariable('argc')
     local var_argc_value = var_argc:GetValueAsSigned(error, 0)
     assertTrue(error:Success())
     assertEquals(var_argc_value, 3)
 end
 
+function _T:TestBreakpointRealCallback()
+    local target = self:create_target()
+    local breakpoint = target:BreakpointCreateByLocation('main.c', 31)
+    assertTrue(breakpoint:IsValid() and breakpoint:GetNumLocations() == 1)
+    local flag = false
+    local i = 1
+    breakpoint:SetScriptCallback(function(frame)
+        flag = true
+        assertEquals(frame:FindVariable('i'):GetValueAsSigned(), i)
+        i = i + 1
+        return false
+    end)
+    target:LaunchSimple(nil, nil, nil)
+    assertTrue(flag)
+end
+
 os.exit(_T:run())