mlir/include/mlir-c/Support.h

   1 //===-- mlir-c/Support.h - Helpers for C API to Core MLIR ---------*- C -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM
   4 // Exceptions.
   5 // See https://llvm.org/LICENSE.txt for license information.
   6 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This header declares the auxiliary data structures used in C APIs to core
  11 // MLIR functionality.
  12 //
  13 //===----------------------------------------------------------------------===//
  14
  15 #ifndef MLIR_C_SUPPORT_H
  16 #define MLIR_C_SUPPORT_H
  17
  18 #include <stdbool.h>
  19 #include <stddef.h>
  20 #include <stdint.h>
  21
  22 //===----------------------------------------------------------------------===//
  23 // Visibility annotations.
  24 // Use MLIR_CAPI_EXPORTED for exported functions.
  25 //
  26 // On Windows, if MLIR_CAPI_ENABLE_WINDOWS_DLL_DECLSPEC is defined, then
  27 // __declspec(dllexport) and __declspec(dllimport) will be generated. This
  28 // can only be enabled if actually building DLLs. It is generally, mutually
  29 // exclusive with the use of other mechanisms for managing imports/exports
  30 // (i.e. CMake's WINDOWS_EXPORT_ALL_SYMBOLS feature).
  31 //===----------------------------------------------------------------------===//
  32
  33 #if (defined(_WIN32) || defined(__CYGWIN__)) &&                                \
  34     !defined(MLIR_CAPI_ENABLE_WINDOWS_DLL_DECLSPEC)
  35 // Visibility annotations disabled.
  36 #define MLIR_CAPI_EXPORTED
  37 #elif defined(_WIN32) || defined(__CYGWIN__)
  38 // Windows visibility declarations.
  39 #if MLIR_CAPI_BUILDING_LIBRARY
  40 #define MLIR_CAPI_EXPORTED __declspec(dllexport)
  41 #else
  42 #define MLIR_CAPI_EXPORTED __declspec(dllimport)
  43 #endif
  44 #else
  45 // Non-windows: use visibility attributes.
  46 #define MLIR_CAPI_EXPORTED __attribute__((visibility("default")))
  47 #endif
  48
  49 #ifdef __cplusplus
  50 extern "C" {
  51 #endif
  52
  53 #define DEFINE_C_API_STRUCT(name, storage)                                     \
  54   struct name {                                                                \
  55     storage *ptr;                                                              \
  56   };                                                                           \
  57   typedef struct name name
  58
  59 /// Re-export llvm::ThreadPool so as to avoid including the LLVM C API directly.
  60 DEFINE_C_API_STRUCT(MlirLlvmThreadPool, void);
  61 DEFINE_C_API_STRUCT(MlirTypeID, const void);
  62 DEFINE_C_API_STRUCT(MlirTypeIDAllocator, void);
  63
  64 #undef DEFINE_C_API_STRUCT
  65
  66 //===----------------------------------------------------------------------===//
  67 // MlirStringRef.
  68 //===----------------------------------------------------------------------===//
  69
  70 /// A pointer to a sized fragment of a string, not necessarily null-terminated.
  71 /// Does not own the underlying string. This is equivalent to llvm::StringRef.
  72
  73 struct MlirStringRef {
  74   const char *data; ///< Pointer to the first symbol.
  75   size_t length;    ///< Length of the fragment.
  76 };
  77 typedef struct MlirStringRef MlirStringRef;
  78
  79 /// Constructs a string reference from the pointer and length. The pointer need
  80 /// not reference to a null-terminated string.
  81
  82 inline static MlirStringRef mlirStringRefCreate(const char *str,
  83                                                 size_t length) {
  84   MlirStringRef result;
  85   result.data = str;
  86   result.length = length;
  87   return result;
  88 }
  89
  90 /// Constructs a string reference from a null-terminated C string. Prefer
  91 /// mlirStringRefCreate if the length of the string is known.
  92 MLIR_CAPI_EXPORTED MlirStringRef
  93 mlirStringRefCreateFromCString(const char *str);
  94
  95 /// Returns true if two string references are equal, false otherwise.
  96 MLIR_CAPI_EXPORTED bool mlirStringRefEqual(MlirStringRef string,
  97                                            MlirStringRef other);
  98
  99 /// A callback for returning string references.
 100 ///
 101 /// This function is called back by the functions that need to return a
 102 /// reference to the portion of the string with the following arguments:
 103 ///  - an MlirStringRef representing the current portion of the string
 104 ///  - a pointer to user data forwarded from the printing call.
 105 typedef void (*MlirStringCallback)(MlirStringRef, void *);
 106
 107 //===----------------------------------------------------------------------===//
 108 // MlirLogicalResult.
 109 //===----------------------------------------------------------------------===//
 110
 111 /// A logical result value, essentially a boolean with named states. LLVM
 112 /// convention for using boolean values to designate success or failure of an
 113 /// operation is a moving target, so MLIR opted for an explicit class.
 114 /// Instances of MlirLogicalResult must only be inspected using the associated
 115 /// functions.
 116 struct MlirLogicalResult {
 117   int8_t value;
 118 };
 119 typedef struct MlirLogicalResult MlirLogicalResult;
 120
 121 /// Checks if the given logical result represents a success.
 122 inline static bool mlirLogicalResultIsSuccess(MlirLogicalResult res) {
 123   return res.value != 0;
 124 }
 125
 126 /// Checks if the given logical result represents a failure.
 127 inline static bool mlirLogicalResultIsFailure(MlirLogicalResult res) {
 128   return res.value == 0;
 129 }
 130
 131 /// Creates a logical result representing a success.
 132 inline static MlirLogicalResult mlirLogicalResultSuccess(void) {
 133   MlirLogicalResult res = {1};
 134   return res;
 135 }
 136
 137 /// Creates a logical result representing a failure.
 138 inline static MlirLogicalResult mlirLogicalResultFailure(void) {
 139   MlirLogicalResult res = {0};
 140   return res;
 141 }
 142
 143 //===----------------------------------------------------------------------===//
 144 // MlirLlvmThreadPool.
 145 //===----------------------------------------------------------------------===//
 146
 147 /// Create an LLVM thread pool. This is reexported here to avoid directly
 148 /// pulling in the LLVM headers directly.
 149 MLIR_CAPI_EXPORTED MlirLlvmThreadPool mlirLlvmThreadPoolCreate(void);
 150
 151 /// Destroy an LLVM thread pool.
 152 MLIR_CAPI_EXPORTED void mlirLlvmThreadPoolDestroy(MlirLlvmThreadPool pool);
 153
 154 //===----------------------------------------------------------------------===//
 155 // TypeID API.
 156 //===----------------------------------------------------------------------===//
 157
 158 /// `ptr` must be 8 byte aligned and unique to a type valid for the duration of
 159 /// the returned type id's usage
 160 MLIR_CAPI_EXPORTED MlirTypeID mlirTypeIDCreate(const void *ptr);
 161
 162 /// Checks whether a type id is null.
 163 static inline bool mlirTypeIDIsNull(MlirTypeID typeID) { return !typeID.ptr; }
 164
 165 /// Checks if two type ids are equal.
 166 MLIR_CAPI_EXPORTED bool mlirTypeIDEqual(MlirTypeID typeID1, MlirTypeID typeID2);
 167
 168 /// Returns the hash value of the type id.
 169 MLIR_CAPI_EXPORTED size_t mlirTypeIDHashValue(MlirTypeID typeID);
 170
 171 //===----------------------------------------------------------------------===//
 172 // TypeIDAllocator API.
 173 //===----------------------------------------------------------------------===//
 174
 175 /// Creates a type id allocator for dynamic type id creation
 176 MLIR_CAPI_EXPORTED MlirTypeIDAllocator mlirTypeIDAllocatorCreate(void);
 177
 178 /// Deallocates the allocator and all allocated type ids
 179 MLIR_CAPI_EXPORTED void
 180 mlirTypeIDAllocatorDestroy(MlirTypeIDAllocator allocator);
 181
 182 /// Allocates a type id that is valid for the lifetime of the allocator
 183 MLIR_CAPI_EXPORTED MlirTypeID
 184 mlirTypeIDAllocatorAllocateTypeID(MlirTypeIDAllocator allocator);
 185
 186 #ifdef __cplusplus
 187 }
 188 #endif
 189
 190 #endif // MLIR_C_SUPPORT_H