[lldb] Deprecate the threading functionality in SBHostOS

[bulbazord]

Summary

SBHostOS implements a threading framework that allows creating and manipulating
OS threads in the current process.

We usually don't deprecate SB APIs, but in this case I think it makes sense because:

• The framework is not implemented on all platforms (i.e. Windows and *BSD support seems to be incomplete)
• ThreadCreated is completely unimplemented..
• It hasn't been touched since the original check-in of the source code.
• I don't think it can even be used via the Python bindings as ThreadCreate seems impossible to call (it takes a function pointer and returns a OS specific struct).
• It's not tested.
• It's to my knowledge not used by Xcode or anyone that has their source code indexed by Google.
• It's the only reason why we (partially) implement a bunch of internal threading utilities in LLDB (which I'll remove in a follow-up patch).

I would propose deprecating it with the upcoming LLDB 13 release (which will be branched in about a month).

[teemperor]

• Remove the deprecation attribute that got inserted by accident.

[teemperor]

Not sure what else we should do to properly deprecate an API. LLVM's approach would be to put [[deprecated("bla")]] the C++ APIs (which would mean you need a C++14 compiler to use the SB API) and there is also the lldb-versioning.h header (which seems to be reserved for actual API breakages).

[labath]

In D104231#2817068, @teemperor wrote:

Not sure what else we should do to properly deprecate an API. LLVM's approach would be to put [[deprecated("bla")]] the C++ APIs (which would mean you need a C++14 compiler to use the SB API)

You can always put the attribute inside an #ifdef c++14.

Another option is to put something like #ifdef LLDB_USE_DEPRECATED_DECLARATIONS around these functions, forcing to user to explicitly request their usage.

Neither of these options will help the usages from python, so it's not a fully general solution, but it sounds like we don't need to worry about that right now...

and there is also the lldb-versioning.h header (which seems to be reserved for actual API breakages).

wow

[bulbazord]

Commandeering this change in order to close it. I've effectively done this already with D153900.

lldb/bindings/interface/SBHostOS.i

public:
     GetLLDBPythonPath ();
 
     static lldb::SBFileSpec
     GetLLDBPath (lldb::PathType path_type);
 
     static lldb::SBFileSpec
     GetUserHomeDirectory ();
 
+
+    %feature("docstring", " .. deprecated:: 13 ") ThreadCreated;
     static void
     ThreadCreated (const char *name);
 
+    %feature("docstring", " .. deprecated:: 13 ") ThreadCreate;
     static lldb::thread_t
     ThreadCreate (const char *name,
                   lldb::thread_func_t,
                   void *thread_arg,
                   lldb::SBError *err);
 
+    %feature("docstring", " .. deprecated:: 13 ") ThreadCancel;
     static bool
     ThreadCancel (lldb::thread_t thread,
                   lldb::SBError *err);
 
+    %feature("docstring", " .. deprecated:: 13 ") ThreadDetach;
     static bool
     ThreadDetach (lldb::thread_t thread,
                   lldb::SBError *err);
+
+    %feature("docstring", " .. deprecated:: 13 ") ThreadJoin;
     static bool
     ThreadJoin (lldb::thread_t thread,
                 lldb::thread_result_t *result,
                 lldb::SBError *err);
 };
 
 } // namespace lldb

lldb/include/lldb/API/SBHostOS.h

 //===-- SBHostOS.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_SBHOSTOS_H
 #define LLDB_API_SBHOSTOS_H
 
 #include "lldb/API/SBDefines.h"
 #include "lldb/API/SBFileSpec.h"
 
 namespace lldb {
 
 class LLDB_API SBHostOS {
 public:
   static lldb::SBFileSpec GetProgramFileSpec();
 
   static lldb::SBFileSpec GetLLDBPythonPath();
 
   static lldb::SBFileSpec GetLLDBPath(lldb::PathType path_type);
 
   static lldb::SBFileSpec GetUserHomeDirectory();
 
+  /// \deprecated Deprecated since LLDB version 13.
   static void ThreadCreated(const char *name);
 
+  /// \deprecated Deprecated since LLDB version 13.
   static lldb::thread_t ThreadCreate(const char *name,
                                      lldb::thread_func_t thread_function,
                                      void *thread_arg, lldb::SBError *err);
 
+  /// \deprecated Deprecated since LLDB version 13.
   static bool ThreadCancel(lldb::thread_t thread, lldb::SBError *err);
 
+  /// \deprecated Deprecated since LLDB version 13.
   static bool ThreadDetach(lldb::thread_t thread, lldb::SBError *err);
+
+  /// \deprecated Deprecated since LLDB version 13.
   static bool ThreadJoin(lldb::thread_t thread, lldb::thread_result_t *result,
                          lldb::SBError *err);
 
 private:
 };
 
 } // namespace lldb
 
 #endif // LLDB_API_SBHOSTOS_H