IODA
c_binding_macros.h
Go to the documentation of this file.
1 #pragma once
2 /*
3  * (C) Copyright 2020-2021 UCAR
4  *
5  * This software is licensed under the terms of the Apache Licence Version 2.0
6  * which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
7  */
8 /*! \defgroup ioda_c_binding_macros C++/C binding macros
9  * \brief Provides the C-style bindings for ioda's templated C++ classes and functions.
10  * \ingroup ioda_c_api
11  *
12  * @{
13  * \file c_binding_macros.h
14  * \brief @link ioda_c_binding_macros C bindings interface @endlink to templated C++ ioda classes
15  * and functions.
16  */
17 
18 #ifndef __cplusplus
19 # include <stdint.h>
20 #else
21 # include <cstdint>
22 # include <iostream>
23 # include <stdexcept>
24 # include <string>
25 # include "ioda/Exception.h"
26 #endif // ifndef __CPLUSPLUS
27 
28 /*! \def C_TRY
29  * \brief Goes with C_CATCH_AND_TERMINATE.
30  */
31 #define C_TRY try {
32 /*! \def C_CATCH_AND_TERMINATE
33  * \brief Catch C++ exceptions before they go across code boundaries.
34  * \details
35  * This is needed because exceptions are not supposed to propagate across language
36  * boundaries. Undefined behavior, and at best the program would terminate cleanly.
37  * This macro ensures that we call std::terminate, which calls std::abort, and
38  * prints an error indicating where this occurs.
39  *
40  * \see C_TRY for the other end of the block.
41  */
42 #define C_CATCH_AND_TERMINATE \
43  } \
44  catch (std::exception & e) { \
45  ioda::unwind_exception_stack(e); \
46  std::terminate(); \
47  } \
48  catch (...) { \
49  std::terminate(); \
50  }
51 
52 /*! \def C_CATCH_AND_RETURN
53  * \brief This macro catches C++ exceptions. If they are recoverable, then return the
54  * error value. If nonrecoverable, behave as C_CATCH_AND_TERMINATE.
55  */
56 #define C_CATCH_AND_RETURN(retval_on_success, retval_on_error) \
57  return (retval_on_success); \
58  } \
59  catch (std::exception & e) { \
60  ioda::unwind_exception_stack(e); \
61  return retval_on_error; \
62  } \
63  catch (...) { \
64  std::terminate(); \
65  }
66 
67 /*! \def C_CATCH_RETURN_FREE
68  * \brief Like C_CATCH_AND_RETURN, but free any in-function allocated C resource before returning
69  * to avoid memory leaks.
70  */
71 #define C_CATCH_RETURN_FREE(retval_on_success, retval_on_error, freeable) \
72  return (retval_on_success); \
73  } \
74  catch (std::exception & e) { \
75  ioda::unwind_exception_stack(e); \
76  delete freeable; \
77  return retval_on_error; \
78  } \
79  catch (...) { \
80  std::terminate(); \
81  }
82 
83 /**
84  * \def C_TEMPLATE_FUNCTION_DEFINITION
85  * \brief Used to expand templates to provide bindings for
86  * template-deprived languages (C, Fortran).
87  * \note There is a similar macro in the ioda python interface.
88  *
89  * \def C_TEMPLATE_FUNCTION_DECLARATION
90  * \brief Used to expand templates to provide bindings for
91  * template-deprived languages (C, Fortran).
92  * \note There is a similar macro in the ioda python interface.
93  **/
94 
95 #define C_TEMPLATE_FUNCTION_DEFINITION_NOSTR(funcname, PATTERN) \
96  PATTERN(funcname##_float, float) \
97  PATTERN(funcname##_double, double) \
98  PATTERN(funcname##_ldouble, long double) \
99  PATTERN(funcname##_char, char) \
100  PATTERN(funcname##_short, short int) \
101  PATTERN(funcname##_ushort, unsigned short int) \
102  PATTERN(funcname##_int, int) \
103  PATTERN(funcname##_uint, unsigned int) \
104  PATTERN(funcname##_lint, long int) \
105  PATTERN(funcname##_ulint, unsigned long int) \
106  PATTERN(funcname##_llint, long long int) \
107  PATTERN(funcname##_ullint, unsigned long long int) \
108  PATTERN(funcname##_int32, int32_t) \
109  PATTERN(funcname##_uint32, uint32_t) \
110  PATTERN(funcname##_int16, int16_t) \
111  PATTERN(funcname##_uint16, uint16_t) \
112  PATTERN(funcname##_int64, int64_t) \
113  PATTERN(funcname##_uint64, uint64_t)
114 /*
115 Problems:
116 PATTERN(funcname ## _bool, bool) \
117 */
118 
119 #define C_TEMPLATE_FUNCTION_DECLARATION_4_NOSTR(shortname, basename, PATTERN) \
120  PATTERN(shortname##_float, basename##_float, float); \
121  PATTERN(shortname##_double, basename##_double, double); \
122  PATTERN(shortname##_ldouble, basename##_ldouble, long double); \
123  PATTERN(shortname##_char, basename##_char, char); \
124  PATTERN(shortname##_short, basename##_short, short); \
125  PATTERN(shortname##_ushort, basename##_ushort, unsigned short); \
126  PATTERN(shortname##_int, basename##_int, int); \
127  PATTERN(shortname##_uint, basename##_uint, unsigned); \
128  PATTERN(shortname##_lint, basename##_lint, long); \
129  PATTERN(shortname##_ulint, basename##_ulint, unsigned long); \
130  PATTERN(shortname##_llint, basename##_llint, long long); \
131  PATTERN(shortname##_ullint, basename##_ullint, unsigned long long); \
132  PATTERN(shortname##_int32, basename##_int32, int32_t); \
133  PATTERN(shortname##_uint32, basename##_uint32, uint32_t); \
134  PATTERN(shortname##_int16, basename##_int16, int16_t); \
135  PATTERN(shortname##_uint16, basename##_uint16, uint16_t); \
136  PATTERN(shortname##_int64, basename##_int64, int64_t); \
137  PATTERN(shortname##_uint64, basename##_uint64, uint64_t);
138 
139 #define C_TEMPLATE_FUNCTION_DECLARATION_3_NOSTR(shortname, basename, PATTERN) \
140  PATTERN(shortname##_float, basename##_float); \
141  PATTERN(shortname##_double, basename##_double); \
142  PATTERN(shortname##_ldouble, basename##_ldouble); \
143  PATTERN(shortname##_char, basename##_char); \
144  PATTERN(shortname##_short, basename##_short); \
145  PATTERN(shortname##_ushort, basename##_ushort); \
146  PATTERN(shortname##_int, basename##_int); \
147  PATTERN(shortname##_uint, basename##_uint); \
148  PATTERN(shortname##_lint, basename##_lint); \
149  PATTERN(shortname##_ulint, basename##_ulint); \
150  PATTERN(shortname##_llint, basename##_llint); \
151  PATTERN(shortname##_ullint, basename##_ullint); \
152  PATTERN(shortname##_int32, basename##_int32); \
153  PATTERN(shortname##_uint32, basename##_uint32); \
154  PATTERN(shortname##_int16, basename##_int16); \
155  PATTERN(shortname##_uint16, basename##_uint16); \
156  PATTERN(shortname##_int64, basename##_int64); \
157  PATTERN(shortname##_uint64, basename##_uint64);
158 
159 #define C_TEMPLATE_FUNCTION_DECLARATION_3(shortname, basename, PATTERN) \
160  C_TEMPLATE_FUNCTION_DECLARATION_3_NOSTR(shortname, basename, PATTERN) \
161  PATTERN(shortname##_str, basename##_str);
162 
163 #define C_TEMPLATE_FUNCTION_DECLARATION_NOSTR(funcname, PATTERN) \
164  C_TEMPLATE_FUNCTION_DECLARATION_3_NOSTR(funcname, funcname, PATTERN)
165 
166 #define C_TEMPLATE_FUNCTION_DECLARATION(funcname, PATTERN) \
167  C_TEMPLATE_FUNCTION_DECLARATION_3_NOSTR(funcname, funcname, PATTERN) \
168  PATTERN(funcname##_str, funcname##_str)
169 
170 #define C_TEMPLATE_FUNCTION_DEFINITION(funcname, PATTERN) \
171  C_TEMPLATE_FUNCTION_DEFINITION_NOSTR(funcname, PATTERN) \
172  PATTERN(funcname##_str, std::string)
173 
174 /// @} // End Doxygen block
Exception.h
IODA's error system.