1 /*===- c_api.h - C API for the ORC runtime ------------------------*- 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 file defines the C API for the ORC runtime *|
11 |* *|
12 \*===----------------------------------------------------------------------===*/
13
14 #ifndef ORC_RT_C_API_H
15 #define ORC_RT_C_API_H
16
17 #include <assert.h>
18 #include <stdio.h>
19 #include <stdlib.h>
20 #include <string.h>
21
22 /* Helper to suppress strict prototype warnings. */
23 #ifdef __clang__
24 #define ORC_RT_C_STRICT_PROTOTYPES_BEGIN \
25 _Pragma("clang diagnostic push") \
26 _Pragma("clang diagnostic error \"-Wstrict-prototypes\"")
27 #define ORC_RT_C_STRICT_PROTOTYPES_END _Pragma("clang diagnostic pop")
28 #else
29 #define ORC_RT_C_STRICT_PROTOTYPES_BEGIN
30 #define ORC_RT_C_STRICT_PROTOTYPES_END
31 #endif
32
33 /* Helper to wrap C code for C++ */
34 #ifdef __cplusplus
35 #define ORC_RT_C_EXTERN_C_BEGIN \
36 extern "C" { \
37 ORC_RT_C_STRICT_PROTOTYPES_BEGIN
38 #define ORC_RT_C_EXTERN_C_END \
39 ORC_RT_C_STRICT_PROTOTYPES_END \
40 }
41 #else
42 #define ORC_RT_C_EXTERN_C_BEGIN ORC_RT_C_STRICT_PROTOTYPES_BEGIN
43 #define ORC_RT_C_EXTERN_C_END ORC_RT_C_STRICT_PROTOTYPES_END
44 #endif
45
46 ORC_RT_C_EXTERN_C_BEGIN
47
48 typedef union {
49 char *ValuePtr;
50 char Value[sizeof(char *)];
51 } orc_rt_CWrapperFunctionResultDataUnion;
52
53 /**
54 * orc_rt_CWrapperFunctionResult is a kind of C-SmallVector with an
55 * out-of-band error state.
56 *
57 * If Size == 0 and Data.ValuePtr is non-zero then the value is in the
58 * 'out-of-band error' state, and Data.ValuePtr points at a malloc-allocated,
59 * null-terminated string error message.
60 *
61 * If Size <= sizeof(orc_rt_CWrapperFunctionResultData) then the value is in
62 * the 'small' state and the content is held in the first Size bytes of
63 * Data.Value.
64 *
65 * If Size > sizeof(OrtRTCWrapperFunctionResultData) then the value is in the
66 * 'large' state and the content is held in the first Size bytes of the
67 * memory pointed to by Data.ValuePtr. This memory must have been allocated by
68 * malloc, and will be freed with free when this value is destroyed.
69 */
70 typedef struct {
71 orc_rt_CWrapperFunctionResultDataUnion Data;
72 size_t Size;
73 } orc_rt_CWrapperFunctionResult;
74
75 /**
76 * Zero-initialize an orc_rt_CWrapperFunctionResult.
77 */
78 static inline void
orc_rt_CWrapperFunctionResultInit(orc_rt_CWrapperFunctionResult * R)79 orc_rt_CWrapperFunctionResultInit(orc_rt_CWrapperFunctionResult *R) {
80 R->Size = 0;
81 R->Data.ValuePtr = 0;
82 }
83
84 /**
85 * Create an orc_rt_CWrapperFunctionResult with an uninitialized buffer of
86 * size Size. The buffer is returned via the DataPtr argument.
87 */
88 static inline orc_rt_CWrapperFunctionResult
orc_rt_CWrapperFunctionResultAllocate(size_t Size)89 orc_rt_CWrapperFunctionResultAllocate(size_t Size) {
90 orc_rt_CWrapperFunctionResult R;
91 R.Size = Size;
92 // If Size is 0 ValuePtr must be 0 or it is considered an out-of-band error.
93 R.Data.ValuePtr = 0;
94 if (Size > sizeof(R.Data.Value))
95 R.Data.ValuePtr = (char *)malloc(Size);
96 return R;
97 }
98
99 /**
100 * Create an orc_rt_WrapperFunctionResult from the given data range.
101 */
102 static inline orc_rt_CWrapperFunctionResult
orc_rt_CreateCWrapperFunctionResultFromRange(const char * Data,size_t Size)103 orc_rt_CreateCWrapperFunctionResultFromRange(const char *Data, size_t Size) {
104 orc_rt_CWrapperFunctionResult R;
105 R.Size = Size;
106 if (R.Size > sizeof(R.Data.Value)) {
107 char *Tmp = (char *)malloc(Size);
108 memcpy(Tmp, Data, Size);
109 R.Data.ValuePtr = Tmp;
110 } else
111 memcpy(R.Data.Value, Data, Size);
112 return R;
113 }
114
115 /**
116 * Create an orc_rt_CWrapperFunctionResult by copying the given string,
117 * including the null-terminator.
118 *
119 * This function copies the input string. The client is responsible for freeing
120 * the ErrMsg arg.
121 */
122 static inline orc_rt_CWrapperFunctionResult
orc_rt_CreateCWrapperFunctionResultFromString(const char * Source)123 orc_rt_CreateCWrapperFunctionResultFromString(const char *Source) {
124 return orc_rt_CreateCWrapperFunctionResultFromRange(Source,
125 strlen(Source) + 1);
126 }
127
128 /**
129 * Create an orc_rt_CWrapperFunctionResult representing an out-of-band
130 * error.
131 *
132 * This function copies the input string. The client is responsible for freeing
133 * the ErrMsg arg.
134 */
135 static inline orc_rt_CWrapperFunctionResult
orc_rt_CreateCWrapperFunctionResultFromOutOfBandError(const char * ErrMsg)136 orc_rt_CreateCWrapperFunctionResultFromOutOfBandError(const char *ErrMsg) {
137 orc_rt_CWrapperFunctionResult R;
138 R.Size = 0;
139 char *Tmp = (char *)malloc(strlen(ErrMsg) + 1);
140 strcpy(Tmp, ErrMsg);
141 R.Data.ValuePtr = Tmp;
142 return R;
143 }
144
145 /**
146 * This should be called to destroy orc_rt_CWrapperFunctionResult values
147 * regardless of their state.
148 */
149 static inline void
orc_rt_DisposeCWrapperFunctionResult(orc_rt_CWrapperFunctionResult * R)150 orc_rt_DisposeCWrapperFunctionResult(orc_rt_CWrapperFunctionResult *R) {
151 if (R->Size > sizeof(R->Data.Value) ||
152 (R->Size == 0 && R->Data.ValuePtr))
153 free(R->Data.ValuePtr);
154 }
155
156 /**
157 * Get a pointer to the data contained in the given
158 * orc_rt_CWrapperFunctionResult.
159 */
160 static inline char *
orc_rt_CWrapperFunctionResultData(orc_rt_CWrapperFunctionResult * R)161 orc_rt_CWrapperFunctionResultData(orc_rt_CWrapperFunctionResult *R) {
162 assert((R->Size != 0 || R->Data.ValuePtr == NULL) &&
163 "Cannot get data for out-of-band error value");
164 return R->Size > sizeof(R->Data.Value) ? R->Data.ValuePtr : R->Data.Value;
165 }
166
167 /**
168 * Safely get the size of the given orc_rt_CWrapperFunctionResult.
169 *
170 * Asserts that we're not trying to access the size of an error value.
171 */
172 static inline size_t
orc_rt_CWrapperFunctionResultSize(const orc_rt_CWrapperFunctionResult * R)173 orc_rt_CWrapperFunctionResultSize(const orc_rt_CWrapperFunctionResult *R) {
174 assert((R->Size != 0 || R->Data.ValuePtr == NULL) &&
175 "Cannot get size for out-of-band error value");
176 return R->Size;
177 }
178
179 /**
180 * Returns 1 if this value is equivalent to a value just initialized by
181 * orc_rt_CWrapperFunctionResultInit, 0 otherwise.
182 */
183 static inline size_t
orc_rt_CWrapperFunctionResultEmpty(const orc_rt_CWrapperFunctionResult * R)184 orc_rt_CWrapperFunctionResultEmpty(const orc_rt_CWrapperFunctionResult *R) {
185 return R->Size == 0 && R->Data.ValuePtr == 0;
186 }
187
188 /**
189 * Returns a pointer to the out-of-band error string for this
190 * orc_rt_CWrapperFunctionResult, or null if there is no error.
191 *
192 * The orc_rt_CWrapperFunctionResult retains ownership of the error
193 * string, so it should be copied if the caller wishes to preserve it.
194 */
orc_rt_CWrapperFunctionResultGetOutOfBandError(const orc_rt_CWrapperFunctionResult * R)195 static inline const char *orc_rt_CWrapperFunctionResultGetOutOfBandError(
196 const orc_rt_CWrapperFunctionResult *R) {
197 return R->Size == 0 ? R->Data.ValuePtr : 0;
198 }
199
200 ORC_RT_C_EXTERN_C_END
201
202 #endif /* ORC_RT_C_API_H */
203