ManagedStatic: mark as deprecated, about to be removed

[nhaehnle]

Summary

This is separate from outright removal so that downstreams that track
the main branch closely can get a small grace period.

[nhaehnle]

Rebase

llvm/docs/ProgrammersManual.rst

 .. _shutdown:
 
 Ending Execution with ``llvm_shutdown()``
 -----------------------------------------
 
 When you are done using the LLVM APIs, you should call ``llvm_shutdown()`` to
 deallocate memory used for internal structures.
 
-.. _managedstatic:
-
-Lazy Initialization with ``ManagedStatic``
-------------------------------------------
-
-``ManagedStatic`` is a utility class in LLVM used to implement static
-initialization of static resources, such as the global type tables.  In a
-single-threaded environment, it implements a simple lazy initialization scheme.
-When LLVM is compiled with support for multi-threading, however, it uses
-double-checked locking to implement thread-safe lazy initialization.
-
 .. _llvmcontext:
 
 Achieving Isolation with ``LLVMContext``
 ----------------------------------------
 
 ``LLVMContext`` is an opaque class in the LLVM API which clients can use to
 operate multiple, isolated instances of LLVM concurrently within the same
 address space.  For instance, in a hypothetical compile-server, the compilation

llvm/include/llvm/Support/ManagedStatic.h

 //===-- llvm/Support/ManagedStatic.h - Static Global wrapper ----*- 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
 //
 //===----------------------------------------------------------------------===//
 //
 // This file defines the ManagedStatic class and the llvm_shutdown() function.

 
 /// ManagedStatic - This transparently changes the behavior of global statics to
 /// be lazily constructed on demand (good for reducing startup times of dynamic
 /// libraries that link in LLVM components) and for making destruction be
 /// explicit through the llvm_shutdown() function call.
 ///
 template <class C, class Creator = object_creator<C>,
           class Deleter = object_deleter<C>>
-class ManagedStatic : public ManagedStaticBase {
+class [[deprecated("ManagedStatic is deprecated and will be removed; use "
+                   "function scope static variables in a getter function "
+                   "instead")]] ManagedStatic : public ManagedStaticBase {
 public:
   // Accessors.
   C &operator*() {
     void *Tmp = Ptr.load(std::memory_order_acquire);
     if (!Tmp)
       RegisterManagedStatic(Creator::call, Deleter::call);
 
     return *static_cast<C *>(Ptr.load(std::memory_order_relaxed));