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
50extern "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.
60DEFINE_C_API_STRUCT(MlirLlvmThreadPool, void);
61DEFINE_C_API_STRUCT(MlirTypeID, const void);
62DEFINE_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
73struct MlirStringRef {
74 const char *data; ///< Pointer to the first symbol.
75 size_t length; ///< Length of the fragment.
76};
77typedef 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
82inline 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.
92MLIR_CAPI_EXPORTED MlirStringRef
93mlirStringRefCreateFromCString(const char *str);
94
95/// Returns true if two string references are equal, false otherwise.
96MLIR_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.
105typedef 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.
116struct MlirLogicalResult {
117 int8_t value;
118};
119typedef struct MlirLogicalResult MlirLogicalResult;
120
121/// Checks if the given logical result represents a success.
122inline static bool mlirLogicalResultIsSuccess(MlirLogicalResult res) {
123 return res.value != 0;
124}
125
126/// Checks if the given logical result represents a failure.
127inline static bool mlirLogicalResultIsFailure(MlirLogicalResult res) {
128 return res.value == 0;
129}
130
131/// Creates a logical result representing a success.
132inline static MlirLogicalResult mlirLogicalResultSuccess(void) {
133 MlirLogicalResult res = {.value: 1};
134 return res;
135}
136
137/// Creates a logical result representing a failure.
138inline static MlirLogicalResult mlirLogicalResultFailure(void) {
139 MlirLogicalResult res = {.value: 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.
149MLIR_CAPI_EXPORTED MlirLlvmThreadPool mlirLlvmThreadPoolCreate(void);
150
151/// Destroy an LLVM thread pool.
152MLIR_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
160MLIR_CAPI_EXPORTED MlirTypeID mlirTypeIDCreate(const void *ptr);
161
162/// Checks whether a type id is null.
163static inline bool mlirTypeIDIsNull(MlirTypeID typeID) { return !typeID.ptr; }
164
165/// Checks if two type ids are equal.
166MLIR_CAPI_EXPORTED bool mlirTypeIDEqual(MlirTypeID typeID1, MlirTypeID typeID2);
167
168/// Returns the hash value of the type id.
169MLIR_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
176MLIR_CAPI_EXPORTED MlirTypeIDAllocator mlirTypeIDAllocatorCreate(void);
177
178/// Deallocates the allocator and all allocated type ids
179MLIR_CAPI_EXPORTED void
180mlirTypeIDAllocatorDestroy(MlirTypeIDAllocator allocator);
181
182/// Allocates a type id that is valid for the lifetime of the allocator
183MLIR_CAPI_EXPORTED MlirTypeID
184mlirTypeIDAllocatorAllocateTypeID(MlirTypeIDAllocator allocator);
185
186#ifdef __cplusplus
187}
188#endif
189
190#endif // MLIR_C_SUPPORT_H
191

source code of mlir/include/mlir-c/Support.h