LLVM C API. Deprecated functions

[AlexDenisov]

Summary

Currently C API contains several deprecated functions,
however the deprecation mentioned only inside a comment around a function.

The patch replaces comment within attribute((deprecated("Use <alternative>"))).

[AlexDenisov]

Forgot to mention initially: the macro LLVM_ATTRIBUTE_DEPRECATED was copied from llvm/Support/Compiler.h

[echristo]

Works for me. Give it a few days in case people want to comment or bikeshed on naming (the file name is a bit weird, but I don't have anything better).

Thanks!

-eric

[echristo]

(In particular adding Mehdi here)

[mehdi_amini]

I like it :)

[AlexDenisov]

I didn't find good name for a new file either :)
So, I will give it a few days and then commit if there are no objections.

[mehdi_amini]

include/llvm-c/Definitions.h

27

Do we have to leave this in include/llvm-c? Could it be somewhere in include/llvm? We may already have a place for such macros.
Also sometimes we keep alive some C++ APIs just for the purpose of supporting a C API, I think we should mark these as deprecated as well so we know we can remove them.

[echristo]

We do already have a place, but I wasn't sure whether or not we wanted a
separate implementation.

[AlexDenisov]

In D18964#397364, @echristo wrote:

We do already have a place, but I wasn't sure whether or not we wanted a
separate implementation.

This is exactly my intention. I copied the definition from llvm/Support/Compiler.h, but besides that it contains a lot of other stuff, that might not be suitable for C API (e.g. sanitizers).
Another possible solution is to introduce another header and include it into both llvm/Support/Compiler.h and C API interface.

Also sometimes we keep alive some C++ APIs just for the purpose of supporting a C API, I think we should mark these as deprecated as well so we know we can remove them.

This is a very good idea, I will skim through the implementations and check whether we can deprecate something there.

[echristo]

I actually think it can just be included. It doesn't include any other
files and seems to be C only.

-eric

[AlexDenisov]

In D18964#397444, @echristo wrote:

I actually think it can just be included. It doesn't include any other
files and seems to be C only.

-eric

Seems it has C++ comments, as well as Definitions.h I introduced.
Should Compiler.h be updated to C-style as well?

include/llvm-c/BitReader.h

 #ifndef LLVM_C_BITREADER_H
 #define LLVM_C_BITREADER_H
 
+#include "llvm-c/Definitions.h"
 #include "llvm-c/Types.h"
 
 #ifdef __cplusplus

 
 /* Builds a module from the bitcode in the specified memory buffer, returning a
    reference to the module via the OutModule parameter. Returns 0 on success.
-   Optionally returns a human-readable error message via OutMessage.
-
-   This is deprecated. Use LLVMParseBitcode2. */
-LLVMBool LLVMParseBitcode(LLVMMemoryBufferRef MemBuf, LLVMModuleRef *OutModule,
-                          char **OutMessage);
+   Optionally returns a human-readable error message via OutMessage. */
+LLVM_ATTRIBUTE_DEPRECATED(
+  LLVMBool LLVMParseBitcode(LLVMMemoryBufferRef MemBuf, 
+                            LLVMModuleRef *OutModule,
+                            char **OutMessage),
+  "Use LLVMParseBitcode2");
 
 /* Builds a module from the bitcode in the specified memory buffer, returning a
    reference to the module via the OutModule parameter. Returns 0 on success. */
 LLVMBool LLVMParseBitcode2(LLVMMemoryBufferRef MemBuf,
                            LLVMModuleRef *OutModule);
 
-/* This is deprecated. Use LLVMParseBitcodeInContext2. */
+LLVM_ATTRIBUTE_DEPRECATED(
     LLVMBool LLVMParseBitcodeInContext(LLVMContextRef ContextRef,
                                        LLVMMemoryBufferRef MemBuf,
-                                   LLVMModuleRef *OutModule, char **OutMessage);
+                                       LLVMModuleRef *OutModule, 
+                                       char **OutMessage),
+  "Use LLVMParseBitcodeInContext2");
 
 LLVMBool LLVMParseBitcodeInContext2(LLVMContextRef ContextRef,
                                     LLVMMemoryBufferRef MemBuf,

 
 /** Reads a module from the specified path, returning via the OutMP parameter
     a module provider which performs lazy deserialization. Returns 0 on success.
-    Optionally returns a human-readable error message via OutMessage.
-    This is deprecated. Use LLVMGetBitcodeModuleInContext2. */
+    Optionally returns a human-readable error message via OutMessage. */
+LLVM_ATTRIBUTE_DEPRECATED(
   LLVMBool LLVMGetBitcodeModuleInContext(LLVMContextRef ContextRef,
                                          LLVMMemoryBufferRef MemBuf,
-                                       LLVMModuleRef *OutM, char **OutMessage);
+                                         LLVMModuleRef *OutM, 
+                                         char **OutMessage),
+  "Use LLVMGetBitcodeModuleInContext2");
 
 /** Reads a module from the specified path, returning via the OutMP parameter a
  * module provider which performs lazy deserialization. Returns 0 on success. */

                                         LLVMMemoryBufferRef MemBuf,
                                         LLVMModuleRef *OutM);
 
-/* This is deprecated. Use LLVMGetBitcodeModule2. */
-LLVMBool LLVMGetBitcodeModule(LLVMMemoryBufferRef MemBuf, LLVMModuleRef *OutM,
-                              char **OutMessage);
+LLVM_ATTRIBUTE_DEPRECATED(
+  LLVMBool LLVMGetBitcodeModule(LLVMMemoryBufferRef MemBuf, 
+                                LLVMModuleRef *OutM,
+                                char **OutMessage),
+  "Use LLVMGetBitcodeModule2");
 
 LLVMBool LLVMGetBitcodeModule2(LLVMMemoryBufferRef MemBuf, LLVMModuleRef *OutM);
 

include/llvm-c/BitWriter.h

 int LLVMWriteBitcodeToFD(LLVMModuleRef M, int FD, int ShouldClose,
                          int Unbuffered);
 
-/** Deprecated for LLVMWriteBitcodeToFD. Writes a module to an open file
-    descriptor. Returns 0 on success. Closes the Handle. */
-int LLVMWriteBitcodeToFileHandle(LLVMModuleRef M, int Handle);
+/** Writes a module to an open file descriptor. Returns 0 on success. 
+    Closes the Handle. */
+LLVM_ATTRIBUTE_DEPRECATED(
+  int LLVMWriteBitcodeToFileHandle(LLVMModuleRef M, int Handle), 
+  "Use LLVMWriteBitcodeToFD");
 
 /** Writes a module to a new memory buffer and returns it. */
 LLVMMemoryBufferRef LLVMWriteBitcodeToMemoryBuffer(LLVMModuleRef M);

include/llvm-c/Core.h

 #ifndef LLVM_C_CORE_H
 #define LLVM_C_CORE_H
 
+#include "llvm-c/Definitions.h"
 #include "llvm-c/ErrorHandling.h"
 #include "llvm-c/Types.h"
 

  * Obtain the data layout for a module.
  *
  * @see Module::getDataLayoutStr()
+ */
+const char *LLVMGetDataLayoutStr(LLVMModuleRef M);
+
+/**
+ * Obtain the data layout for a module.
+ *
+ * @see Module::getDataLayoutStr()
  *
  * LLVMGetDataLayout is DEPRECATED, as the name is not only incorrect,
  * but match the name of another method on the module. Prefer the use
  * of LLVMGetDataLayoutStr, which is not ambiguous.
  */
-const char *LLVMGetDataLayoutStr(LLVMModuleRef M);
-const char *LLVMGetDataLayout(LLVMModuleRef M);
+LLVM_ATTRIBUTE_DEPRECATED(
+  const char *LLVMGetDataLayout(LLVMModuleRef M), 
+  "Use LLVMGetDataLayoutStr");
 
 /**
  * Set the data layout for a module.

     @see llvm::FunctionPassManager::FunctionPassManager */
 LLVMPassManagerRef LLVMCreateFunctionPassManagerForModule(LLVMModuleRef M);
 
-/** Deprecated: Use LLVMCreateFunctionPassManagerForModule instead. */
-LLVMPassManagerRef LLVMCreateFunctionPassManager(LLVMModuleProviderRef MP);
+LLVM_ATTRIBUTE_DEPRECATED(
+  LLVMPassManagerRef LLVMCreateFunctionPassManager(LLVMModuleProviderRef MP), 
+  "Use LLVMCreateFunctionPassManagerForModule");
 
 /** Initializes, executes on the provided module, and finalizes all of the
     passes scheduled in the pass manager. Returns 1 if any of the passes

  * @{
  */
 
-/** Deprecated: Multi-threading can only be enabled/disabled with the compile
-    time define LLVM_ENABLE_THREADS.  This function always returns
-    LLVMIsMultithreaded(). */
-LLVMBool LLVMStartMultithreaded(void);
+LLVM_ATTRIBUTE_DEPRECATED(
+  LLVMBool LLVMStartMultithreaded(void), 
+  "Multi-threading can only be enabled/disabled with the compile "
+  "time define LLVM_ENABLE_THREADS. This function always returns "
+  "LLVMIsMultithreaded()");
 
-/** Deprecated: Multi-threading can only be enabled/disabled with the compile
-    time define LLVM_ENABLE_THREADS. */
-void LLVMStopMultithreaded(void);
+LLVM_ATTRIBUTE_DEPRECATED(
+  void LLVMStopMultithreaded(void), 
+  "Multi-threading can only be enabled/disabled with the compile "
+  "time define LLVM_ENABLE_THREADS");
 
 /** Check whether LLVM is executing in thread-safe mode or not.
     @see llvm::llvm_is_multithreaded */

include/llvm-c/Definitions.h

+//===-- llvm-c/Definitions.h - C API Macros --*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+//
+// This file is intended to hold macros used all over the C API.
+//
+//===----------------------------------------------------------------------===//
+
+// LLVM_ATTRIBUTE_DEPRECATED(decl, "message")
+#if __has_feature(attribute_deprecated_with_message)
+# define LLVM_ATTRIBUTE_DEPRECATED(decl, message) \
+  decl __attribute__((deprecated(message)))
+#elif defined(__GNUC__)
+# define LLVM_ATTRIBUTE_DEPRECATED(decl, message) \
+  decl __attribute__((deprecated))
+#elif defined(_MSC_VER)
+# define LLVM_ATTRIBUTE_DEPRECATED(decl, message) \
+  __declspec(deprecated(message)) decl
+#else
+# define LLVM_ATTRIBUTE_DEPRECATED(decl, message) \
+  decl
+#endif