[lldb-dap] Adding support for cancelling a request.

Adding support for cancelling requests.

There are two forms of request cancellation.

* Preemptively cancelling a request that is in the queue.
* Actively cancelling the in progress request as a best effort attempt using `SBDebugger.RequestInterrupt()`.

Author: ashgti

lldb/test/API/tools/lldb-dap/cancel/Makefile

@@ -0,0 +1,3 @@
+C_SOURCES := main.c
+
+include Makefile.rules

lldb/test/API/tools/lldb-dap/cancel/TestDAP_cancel.py

@@ -0,0 +1,92 @@
+"""
+Test lldb-dap cancel request
+"""
+
+from lldbsuite.test.decorators import *
+from lldbsuite.test.lldbtest import *
+import lldbdap_testcase
+
+
+class TestDAP_launch(lldbdap_testcase.DAPTestCaseBase):
+    def send_async_req(self, command: str, arguments={}) -> int:
+        seq = self.dap_server.sequence
+        self.dap_server.send_packet(
+            {
+                "type": "request",
+                "command": command,
+                "arguments": arguments,
+            }
+        )
+        return seq
+
+    def async_blocking_request(self, duration: float) -> int:
+        """
+        Sends an evaluate request that will sleep for the specified duration to
+        block the request handling thread.
+        """
+        return self.send_async_req(
+            command="evaluate",
+            arguments={
+                "expression": "`script import time; time.sleep({})".format(duration),
+                "context": "repl",
+            },
+        )
+
+    def async_cancel(self, requestId: int) -> int:
+        return self.send_async_req(command="cancel", arguments={"requestId": requestId})
+
+    def test_pending_request(self):
+        """
+        Tests cancelling a pending request.
+        """
+        program = self.getBuildArtifact("a.out")
+        self.build_and_launch(program, stopOnEntry=True)
+        self.continue_to_next_stop()
+
+        # Use a relatively short timeout since this is only to ensure the
+        # following request is queued.
+        blocking_seq = self.async_blocking_request(duration=1.0)
+        # Use a longer timeout to ensure we catch if the request was interrupted
+        # properly.
+        pending_seq = self.async_blocking_request(duration=self.timeoutval)
+        cancel_seq = self.async_cancel(requestId=pending_seq)
+
+        blocking_resp = self.dap_server.recv_packet(filter_type=["response"])
+        self.assertEqual(blocking_resp["request_seq"], blocking_seq)
+        self.assertEqual(blocking_resp["command"], "evaluate")
+        self.assertEqual(blocking_resp["success"], True)
+
+        pending_resp = self.dap_server.recv_packet(filter_type=["response"])
+        self.assertEqual(pending_resp["request_seq"], pending_seq)
+        self.assertEqual(pending_resp["command"], "evaluate")
+        self.assertEqual(pending_resp["success"], False)
+        self.assertEqual(pending_resp["message"], "cancelled")
+
+        cancel_resp = self.dap_server.recv_packet(filter_type=["response"])
+        self.assertEqual(cancel_resp["request_seq"], cancel_seq)
+        self.assertEqual(cancel_resp["command"], "cancel")
+        self.assertEqual(cancel_resp["success"], True)
+        self.continue_to_exit()
+
+    def test_inflight_request(self):
+        """
+        Tests cancelling an inflight request.
+        """
+        program = self.getBuildArtifact("a.out")
+        self.build_and_launch(program, stopOnEntry=True)
+        self.continue_to_next_stop()
+
+        blocking_seq = self.async_blocking_request(duration=self.timeoutval)
+        cancel_seq = self.async_cancel(requestId=blocking_seq)
+
+        blocking_resp = self.dap_server.recv_packet(filter_type=["response"])
+        self.assertEqual(blocking_resp["request_seq"], blocking_seq)
+        self.assertEqual(blocking_resp["command"], "evaluate")
+        self.assertEqual(blocking_resp["success"], False)
+        self.assertEqual(blocking_resp["message"], "cancelled")
+
+        cancel_resp = self.dap_server.recv_packet(filter_type=["response"])
+        self.assertEqual(cancel_resp["request_seq"], cancel_seq)
+        self.assertEqual(cancel_resp["command"], "cancel")
+        self.assertEqual(cancel_resp["success"], True)
+        self.continue_to_exit()

lldb/test/API/tools/lldb-dap/cancel/main.c

@@ -0,0 +1,6 @@
+#include <stdio.h>
+
+int main(int argc, char const *argv[]) {
+  printf("Hello world!\n");
+  return 0;
+}

lldb/tools/lldb-dap/CMakeLists.txt

@@ -41,6 +41,7 @@ add_lldb_tool(lldb-dap
   Handler/ResponseHandler.cpp
   Handler/AttachRequestHandler.cpp
   Handler/BreakpointLocationsHandler.cpp
+  Handler/CancelRequestHandler.cpp
   Handler/CompileUnitsRequestHandler.cpp
   Handler/CompletionsHandler.cpp
   Handler/ConfigurationDoneRequestHandler.cpp

lldb/tools/lldb-dap/DAP.cpp

@@ -37,6 +37,7 @@
 #include <algorithm>
 #include <cassert>
 #include <chrono>
+#include <condition_variable>
 #include <cstdarg>
 #include <cstdio>
 #include <fstream>
@@ -256,7 +257,27 @@ void DAP::SendJSON(const llvm::json::Value &json) {
     }
     return;
   }
-  auto status = transport.Write(log, M);
+  Send(M);
+}
+
+void DAP::Send(const protocol::Message &M) {
+  lldb_private::Status status;
+  // If the debugger was interrupted while handling a response, mark the
+  // response as cancelled since it may contain partial information.
+  if (const auto *resp = std::get_if<protocol::Response>(&M);
+      debugger.InterruptRequested()) {
+    status = transport.Write(
+        log, protocol::Response{
+                 /*request_seq=*/resp->request_seq,
+                 /*command=*/resp->command,
+                 /*success=*/false,
+                 /*message=*/protocol::Response::Message::cancelled,
+                 /*rawBody=*/std::nullopt,
+             });
+  } else {
+    status = transport.Write(log, M);
+  }
+
   if (status.Fail() && log)
     *log << llvm::formatv("failed to send {0}: {1}\n", llvm::json::Value(M),
                           status.AsCString())
@@ -798,22 +819,112 @@ lldb::SBError DAP::Disconnect(bool terminateDebuggee) {
   return error;
 }
 
+template <typename T>
+static std::optional<T> getArgumentsIfRequest(const protocol::Message &pm,
+                                              llvm::StringLiteral command) {
+  auto *const req = std::get_if<protocol::Request>(&pm);
+  if (!req || req->command != command)
+    return std::nullopt;
+
+  T args;
+  llvm::json::Path::Root root;
+  if (!fromJSON(req->rawArguments, args, root)) {
+    return std::nullopt;
+  }
+
+  return std::move(args);
+}
+
 llvm::Error DAP::Loop() {
-  auto cleanup = llvm::make_scope_exit([this]() { StopEventHandlers(); });
+  std::deque<protocol::Message> queue;
+  std::condition_variable queue_cv;
+  std::mutex queue_mutex;
+  std::thread queue_reader([&]() {
+    auto cleanup = llvm::make_scope_exit([&]() {
+      // Ensure we're marked as disconnecting when the reader exits.
+      disconnecting = true;
+      queue_cv.notify_all();
+    });
+    while (!disconnecting) {
+      protocol::Message next;
+      auto status = transport.Read(log, next);
+      if (status.Fail()) {
+        if (status.GetError() != Transport::kEOF && log)
+          *log << "DAP transport failure: " << status.AsCString() << std::endl;
+        break;
+      }
+
+      {
+        std::lock_guard<std::mutex> lock(queue_mutex);
+
+        // If a cancel is requested for the active request, make a best
+        // effort attempt to interrupt.
+        if (const auto args = getArgumentsIfRequest<protocol::CancelArguments>(
+                next, "cancel");
+            args && active_seq == args->requestId)
+          debugger.RequestInterrupt();
+
+        queue.push_back(std::move(next));
+      }
+      queue_cv.notify_one();
+    }
+  });
+
+  auto cleanup = llvm::make_scope_exit([&]() {
+    StopEventHandlers();
+    queue_reader.join();
+  });
+
   while (!disconnecting) {
     protocol::Message next;
-    auto status = transport.Read(log, next);
-    if (status.Fail()) {
-      // On EOF, simply break out of the loop.
-      if (status.GetError() == Transport::kEOF)
+    {
+      std::unique_lock<std::mutex> lock(queue_mutex);
+      queue_cv.wait(lock, [&] { return disconnecting || !queue.empty(); });
+
+      if (queue.empty())
         break;
-      return status.takeError();
+
+      next = queue.front();
+      queue.pop_front();
+
+      if (protocol::Request *req = std::get_if<protocol::Request>(&next)) {
+        active_seq = req->seq;
+
+        // Check if we should preempt this request from a queued cancel.
+        bool cancelled = false;
+        for (const auto &message : queue) {
+          if (const auto args =
+                  getArgumentsIfRequest<protocol::CancelArguments>(message,
+                                                                   "cancel");
+              args && args->requestId == req->seq) {
+            cancelled = true;
+            break;
+          }
+        }
+
+        // Preempt the request and immeidately respond with cancelled.
+        if (cancelled) {
+          Send(protocol::Response{
+              /*request_seq=*/req->seq,
+              /*command=*/req->command,
+              /*success=*/false,
+              /*message=*/protocol::Response::Message::cancelled,
+              /*rawBody=*/std::nullopt,
+          });
+          continue;
+        }
+      } else
+        active_seq = 0;
     }
 
     if (!HandleObject(next)) {
       return llvm::createStringError(llvm::inconvertibleErrorCode(),
                                      "unhandled packet");
     }
+
+    // Clear interrupt marker prior to handling the next request.
+    if (debugger.InterruptRequested())
+      debugger.CancelInterruptRequest();
   }
 
   return llvm::Error::success();

lldb/tools/lldb-dap/DAP.h

@@ -391,6 +391,11 @@ struct DAP {
   InstructionBreakpoint *GetInstructionBreakpoint(const lldb::break_id_t bp_id);
 
   InstructionBreakpoint *GetInstructionBPFromStopReason(lldb::SBThread &thread);
+
+private:
+  void Send(const protocol::Message &M);
+
+  std::atomic<int64_t> active_seq;
 };
 
 template <typename Body>

lldb/tools/lldb-dap/Handler/CancelRequestHandler.cpp

@@ -0,0 +1,56 @@
+//===-- SourceRequestHandler.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 "Protocol.h"
+#include "RequestHandler.h"
+#include "llvm/Support/Error.h"
+
+using namespace lldb_dap;
+using namespace lldb_dap::protocol;
+
+namespace lldb_dap {
+
+// "CancelRequest": {
+//   "allOf": [ { "$ref": "#/definitions/Request" }, {
+//     "type": "object",
+//     "description": "The `cancel` request is used by the client in two
+//     situations:\n- to indicate that it is no longer interested in the result
+//     produced by a specific request issued earlier\n- to cancel a progress
+//     sequence.\nClients should only call this request if the corresponding
+//     capability `supportsCancelRequest` is true.\nThis request has a hint
+//     characteristic: a debug adapter can only be expected to make a 'best
+//     effort' in honoring this request but there are no guarantees.\nThe
+//     `cancel` request may return an error if it could not cancel an operation
+//     but a client should refrain from presenting this error to end users.\nThe
+//     request that got cancelled still needs to send a response back. This can
+//     either be a normal result (`success` attribute true) or an error response
+//     (`success` attribute false and the `message` set to
+//     `cancelled`).\nReturning partial results from a cancelled request is
+//     possible but please note that a client has no generic way for detecting
+//     that a response is partial or not.\nThe progress that got cancelled still
+//     needs to send a `progressEnd` event back.\n A client should not assume
+//     that progress just got cancelled after sending the `cancel` request.",
+//     "properties": {
+//       "command": {
+//         "type": "string",
+//         "enum": [ "cancel" ]
+//       },
+//       "arguments": {
+//         "$ref": "#/definitions/CancelArguments"
+//       }
+//     },
+//     "required": [ "command" ]
+//   }]
+// },
+llvm::Expected<CancelResponseBody>
+CancelRequestHandler::Run(const CancelArguments &arguments) const {
+  /* no-op, simple ack of the request. */
+  return nullptr;
+}
+
+} // namespace lldb_dap

lldb/tools/lldb-dap/Handler/InitializeRequestHandler.cpp

@@ -422,6 +422,7 @@ void InitializeRequestHandler::operator()(
   // The debug adapter support for instruction breakpoint.
   body.try_emplace("supportsInstructionBreakpoints", true);
 
+
   llvm::json::Array completion_characters;
   completion_characters.emplace_back(".");
   completion_characters.emplace_back(" ");
@@ -464,6 +465,8 @@ void InitializeRequestHandler::operator()(
   body.try_emplace("supportsDataBreakpoints", true);
   // The debug adapter supports the `readMemory` request.
   body.try_emplace("supportsReadMemoryRequest", true);
+  // The debug adapter supports the `cancel` request.
+  body.try_emplace("supportsCancelRequest", true);
 
   // Put in non-DAP specification lldb specific information.
   llvm::json::Object lldb_json;

lldb/tools/lldb-dap/Handler/RequestHandler.h

@@ -354,6 +354,16 @@ class ReadMemoryRequestHandler : public BaseRequestHandler {
   void operator()(const llvm::json::Object &request) const override;
 };
 
+class CancelRequestHandler
+    : public RequestHandler<protocol::CancelArguments,
+                            protocol::CancelResponseBody> {
+public:
+  using RequestHandler::RequestHandler;
+  static llvm::StringLiteral getCommand() { return "cancel"; }
+  llvm::Expected<protocol::CancelResponseBody>
+  Run(const protocol::CancelArguments &args) const override;
+};
+
 /// A request used in testing to get the details on all breakpoints that are
 /// currently set in the target. This helps us to test "setBreakpoints" and
 /// "setFunctionBreakpoints" requests to verify we have the correct set of

lldb/tools/lldb-dap/Protocol.cpp

@@ -319,6 +319,13 @@ llvm::json::Value toJSON(const ExitedEventBody &EEB) {
   return llvm::json::Object{{"exitCode", EEB.exitCode}};
 }
 
+bool fromJSON(const llvm::json::Value &Params, CancelArguments &CA,
+              llvm::json::Path P) {
+  llvm::json::ObjectMapper O(Params, P);
+  return O && O.mapOptional("requestId", CA.requestId) &&
+         O.mapOptional("progressId", CA.progressId);
+}
+
 bool fromJSON(const llvm::json::Value &Params, SourceArguments &SA,
               llvm::json::Path P) {
   llvm::json::ObjectMapper O(Params, P);