Support reuse lldb-dap across VSCode debug sessions

Summary:
This diff adds a new mode in lldb-dap to support reusing lldb-dap across debug sessions which can improve incremental debug session launch/attach time.

The reuse lldb-dap design is implemented by two parts:
* Changes in VSCode fb-lldb extension to decide the reuse policy. Like how long to keep lldb-dap alive, when to reuse, when to spawn a separate instance (like support parallel debug sessions). D59239749 and D58840599
* A new `--keep-alive <timeout_in_ms>` option is added to lldb-dap to keep lldb-dap alive. This diff.

To support keep alive, a new `waitDataAvailableOrTimeout()` function is added in I/O code of lldb-dap to wait for next packet or specified timeout. And the DAP loop will wait for next packet with timeout after disconnection instead of exiting. Also, the global DAP object is reset to initial state.

Test framework is updated to support keep-alive mode and a new test case is added to demonstrate reuse across debug sessions.

Since this feature depends on two parts collaboration, the best way is first landing it as an internal patch for dogfooding (controlled by VSCode fb-lldb options) so that we can surface issues out of it. Once we feel confident about the feature, I will bring it to upstream.

Test Plan:
Test framework is updated to support keep-alive mode and a new test case is added to demonstrate reuse across debug sessions.

Measured performance improvement for incremental debug sessions:
```
adfinder built with ads focused mode:
* changed from 35s => 6s

//systemhealth/parrot:parrot_debug built with mode/lldb:
* 13GB of debug info and 199 total modules (3 modules hydrated with symbol on-demand)
* changed from 55s => 5s

//fblearner/feature_store/cpp:server built with mode/lldb:
* 58GB of debug info and 889 total modules (2 modules hydrated with symbol on-demand)
* changed from 110s => 11s

```

Reviewers: freik, gclayton, toyang, wanyi, #lldb_team

Reviewed By: freik

Subscribers: freik, #lldb_team

Differential Revision: https://phabricator.intern.facebook.com/D59401005

Author: Jeffrey Tan

lldb/include/lldb/API/SBDebugger.h

@@ -385,6 +385,10 @@ class LLDB_API SBDebugger {
                                            const char *value,
                                            const char *debugger_instance_name);
 
+  static lldb::SBError
+  ClearInternalVariable(const char *var_name,
+                        const char *debugger_instance_name);
+
   static lldb::SBStringList
   GetInternalVariableValue(const char *var_name,
                            const char *debugger_instance_name);

lldb/packages/Python/lldbsuite/test/tools/lldb-dap/dap_server.py

@@ -146,33 +146,43 @@ def __init__(
         send: BinaryIO,
         init_commands: list[str],
         log_file: Optional[TextIO] = None,
+        keepAlive=False,
     ):
         # For debugging test failures, try setting `trace_file = sys.stderr`.
         self.trace_file: Optional[TextIO] = None
         self.log_file = log_file
+        self.trace_file = None
         self.send = send
         self.recv = recv
         self.recv_packets: list[Optional[ProtocolMessage]] = []
         self.recv_condition = threading.Condition()
         self.recv_thread = threading.Thread(target=self._read_packet_thread)
+        self.sequence = 1
+        self.recv_thread.start()
+        self.output_condition = threading.Condition()
+        self.reset(init_commands, keepAlive)
+
+    # This will be called to re-initialize DebugCommunication object during
+    # reusing lldb-dap.
+    def reset(self, init_commands, keepAlive=False):
+        self.trace_file = None
+        self.recv_packets = []
         self.process_event_body = None
         self.exit_status: Optional[int] = None
         self.capabilities: dict[str, Any] = {}
         self.progress_events: list[Event] = []
         self.thread_events_body = []
         self.reverse_requests = []
-        self.sequence = 1
         self.threads = None
         self.thread_stop_reasons = {}
-        self.recv_thread.start()
-        self.output_condition = threading.Condition()
         self.output: dict[str, list[str]] = {}
         self.configuration_done_sent = False
         self.initialized = False
         self.frame_scopes = {}
         self.init_commands = init_commands
         self.resolved_breakpoints = {}
         self.initialized_event = None
+        self.keepAlive = keepAlive
 
     @classmethod
     def encode_content(cls, s: str) -> bytes:
@@ -321,7 +331,9 @@ def _handle_recv_packet(self, packet: Optional[ProtocolMessage]) -> bool:
 
         elif packet_type == "response":
             if packet["command"] == "disconnect":
-                keepGoing = False
+                # Disconnect response should exit the packet read loop unless
+                # client wants to keep adapter alive for reusing.
+                keepGoing = self.keepAlive
         self._enqueue_recv_packet(packet)
         return keepGoing
 
@@ -1322,12 +1334,17 @@ def __init__(
         init_commands: list[str] = [],
         log_file: Optional[TextIO] = None,
         env: Optional[dict[str, str]] = None,
+        keepAliveTimeout: Optional[int] = None,
     ):
         self.process = None
         self.connection = None
         if executable is not None:
             process, connection = DebugAdapterServer.launch(
-                executable=executable, connection=connection, env=env, log_file=log_file
+                executable=executable,
+                connection=connection,
+                env=env,
+                log_file=log_file,
+                keepAliveTimeout=keepAliveTimeout,
             )
             self.process = process
             self.connection = connection
@@ -1349,9 +1366,22 @@ def __init__(
             self.connection = connection
         else:
             DebugCommunication.__init__(
-                self, self.process.stdout, self.process.stdin, init_commands, log_file
+                self,
+                self.process.stdout,
+                self.process.stdin,
+                init_commands,
+                log_file,
+                keepAlive=(keepAliveTimeout is not None),
             )
 
+    @staticmethod
+    def get_args(executable, keepAliveTimeout=None):
+        return (
+            [executable]
+            if keepAliveTimeout is None
+            else [executable, "--keep-alive", str(keepAliveTimeout)]
+        )
+
     @classmethod
     def launch(
         cls,
@@ -1360,14 +1390,15 @@ def launch(
         env: Optional[dict[str, str]] = None,
         log_file: Optional[TextIO] = None,
         connection: Optional[str] = None,
+        keepAliveTimeout: Optional[int] = None,
     ) -> tuple[subprocess.Popen, Optional[str]]:
         adapter_env = os.environ.copy()
         if env is not None:
             adapter_env.update(env)
 
         if log_file:
             adapter_env["LLDBDAP_LOG"] = log_file
-        args = [executable]
+        args = cls.get_args(executable, keepAliveTimeout)
 
         if connection is not None:
             args.append("--connection")
@@ -1748,6 +1779,14 @@ def main():
         ),
     )
 
+    parser.add_option(
+        "--keep-alive",
+        type="int",
+        dest="keepAliveTimeout",
+        help="The number of milliseconds to keep lldb-dap alive after client disconnection for reusing. Zero or negative value will not keep lldb-dap alive.",
+        default=None,
+    )
+
     (options, args) = parser.parse_args(sys.argv[1:])
 
     if options.vscode_path is None and options.connection is None:
@@ -1758,7 +1797,9 @@ def main():
         )
         return
     dbg = DebugAdapterServer(
-        executable=options.vscode_path, connection=options.connection
+        executable=options.vscode_path,
+        connection=options.connection,
+        keepAliveTimeout=options.keepAliveTimeout,
     )
     if options.debug:
         raw_input('Waiting for debugger to attach pid "%i"' % (dbg.get_pid()))

lldb/packages/Python/lldbsuite/test/tools/lldb-dap/lldbdap_testcase.py

@@ -15,32 +15,50 @@ class DAPTestCaseBase(TestBase):
     # timeout by a factor of 10 if ASAN is enabled.
     DEFAULT_TIMEOUT = 10 * (10 if ("ASAN_OPTIONS" in os.environ) else 1)
     NO_DEBUG_INFO_TESTCASE = True
+    # Caches last dap server for reusing.
+    alive_dap_server = None
 
     def create_debug_adapter(
         self,
         lldbDAPEnv: Optional[dict[str, str]] = None,
+        keepAliveTimeout: Optional[int] = None,
+        reuseDapServer: bool = False,
         connection: Optional[str] = None,
     ):
         """Create the Visual Studio Code debug adapter"""
         self.assertTrue(
             is_exe(self.lldbDAPExec), "lldb-dap must exist and be executable"
         )
         log_file_path = self.getBuildArtifact("dap.txt")
+
+        if reuseDapServer:
+            self.assertIsNotNone(
+                DAPTestCaseBase.alive_dap_server, "No alive dap server found."
+            )
+            self.dap_server = DAPTestCaseBase.alive_dap_server
+            self.dap_server.reset(self.setUpCommands(), keepAlive=True)
+            return
+
         self.dap_server = dap_server.DebugAdapterServer(
             executable=self.lldbDAPExec,
             connection=connection,
             init_commands=self.setUpCommands(),
             log_file=log_file_path,
             env=lldbDAPEnv,
+            keepAliveTimeout=keepAliveTimeout,
         )
+        if keepAliveTimeout is not None:
+            # Keep alive for future reuse
+            DAPTestCaseBase.alive_dap_server = self.dap_server
 
     def build_and_create_debug_adapter(
         self,
         lldbDAPEnv: Optional[dict[str, str]] = None,
+        keepAliveTimeout: Optional[int] = None,
         dictionary: Optional[dict] = None,
     ):
         self.build(dictionary=dictionary)
-        self.create_debug_adapter(lldbDAPEnv)
+        self.create_debug_adapter(lldbDAPEnv, keepAliveTimeout)
 
     def build_and_create_debug_adapter_for_attach(self):
         """Variant of build_and_create_debug_adapter that builds a uniquely
@@ -483,12 +501,13 @@ def build_and_launch(
         program,
         *,
         lldbDAPEnv: Optional[dict[str, str]] = None,
+        keepAliveTimeout: Optional[int] = None,
         **kwargs,
     ):
         """Build the default Makefile target, create the DAP debug adapter,
         and launch the process.
         """
-        self.build_and_create_debug_adapter(lldbDAPEnv)
+        self.build_and_create_debug_adapter(lldbDAPEnv, keepAliveTimeout)
         self.assertTrue(os.path.exists(program), "executable must exist")
 
         return self.launch(program, **kwargs)

lldb/source/API/SBDebugger.cpp

@@ -1307,6 +1307,28 @@ const char *SBDebugger::GetInstanceName() {
   return ConstString(m_opaque_sp->GetInstanceName()).AsCString();
 }
 
+SBError SBDebugger::ClearInternalVariable(const char *var_name,
+                                          const char *debugger_instance_name) {
+  LLDB_INSTRUMENT_VA(var_name, debugger_instance_name);
+
+  SBError sb_error;
+  DebuggerSP debugger_sp(
+      Debugger::FindDebuggerWithInstanceName(debugger_instance_name));
+  Status error;
+  if (debugger_sp) {
+    ExecutionContext exe_ctx(
+        debugger_sp->GetCommandInterpreter().GetExecutionContext());
+    error = debugger_sp->SetPropertyValue(&exe_ctx, eVarSetOperationClear,
+                                          var_name, llvm::StringRef());
+  } else {
+    error.FromErrorStringWithFormat("invalid debugger instance name '%s'",
+                                    debugger_instance_name);
+  }
+  if (error.Fail())
+    sb_error.SetError(std::move(error));
+  return sb_error;
+}
+
 SBError SBDebugger::SetInternalVariable(const char *var_name, const char *value,
                                         const char *debugger_instance_name) {
   LLDB_INSTRUMENT_VA(var_name, value, debugger_instance_name);

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

@@ -0,0 +1,3 @@
+CXX_SOURCES := main.cpp
+
+include Makefile.rules

lldb/test/API/tools/lldb-dap/reuseDAP/TestDAP_reuseAdapter.py

@@ -0,0 +1,39 @@
+"""
+Test reuse lldb-dap adapter across debug sessions.
+"""
+
+import dap_server
+from lldbsuite.test.decorators import *
+from lldbsuite.test.lldbtest import *
+from lldbsuite.test import lldbutil
+import lldbdap_testcase
+import time
+import os
+
+
+class TestDAP_reuseAdpater(lldbdap_testcase.DAPTestCaseBase):
+    @skipIfWindows
+    def test_basic_reuse(self):
+        """
+        Test reuse lldb-dap works across debug sessions.
+        """
+        program = self.getBuildArtifact("a.out")
+
+        # Keep lldb-dap alive for 10 minutes.
+        dapKeepAliveTimeInMS = 10 * 1000 * 60 
+        self.build_and_launch(program, disconnectAutomatically=False, keepAliveTimeout=dapKeepAliveTimeInMS)
+
+        source = "main.cpp"
+        breakpoint1_line = line_number(source, "// breakpoint 1")
+        breakpoint_ids = self.set_source_breakpoints(source, [breakpoint1_line])
+        self.continue_to_breakpoints(breakpoint_ids)
+        self.dap_server.request_disconnect()
+
+        # Second debug session by reusing lldb-dap.
+        self.create_debug_adapter(reuseDapServer=True)
+        self.launch(program)
+        
+        breakpoint2_line = line_number(source, "// breakpoint 2")
+        breakpoint_ids = self.set_source_breakpoints(source, [breakpoint2_line])
+        self.continue_to_breakpoints(breakpoint_ids)
+        self.dap_server.request_disconnect()

lldb/test/API/tools/lldb-dap/reuseDAP/main.cpp

@@ -0,0 +1,15 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+
+int main(int argc, char const *argv[], char const *envp[]) {
+  for (int i = 0; i < argc; ++i)
+    printf("arg[%i] = \"%s\"\n", i, argv[i]);
+  for (int i = 0; envp[i]; ++i)
+    printf("env[%i] = \"%s\"\n", i, envp[i]);
+  char *cwd = getcwd(NULL, 0);
+  printf("cwd = \"%s\"\n", cwd); // breakpoint 1
+  free(cwd);
+  cwd = NULL;
+  return 0; // breakpoint 2
+}