394aed0e4c01a21b8f078118ef7c64b42fcff02e
[asterisk/asterisk.git] / include / asterisk / optional_api.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2008-2013, Digium, Inc.
5  *
6  * Kevin P. Fleming <kpfleming@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 #ifndef __ASTERISK_OPTIONAL_API_H
20 #define __ASTERISK_OPTIONAL_API_H
21
22 /*!
23  * \file
24  * \brief Optional API function macros
25  *
26  * Some Asterisk API functions are provided by loadable modules, thus,
27  * they may or may not be available at run time depending on whether the
28  * providing module has been loaded or not. In addition, there are some
29  * modules that are consumers of these APIs that *optionally* use them; they
30  * have only a part of their functionality dependent on the APIs, and can
31  * provide the remainder even if the APIs are not available.
32  *
33  * An example can be found in agi.h:
34  *
35  * \code
36  * AST_OPTIONAL_API(int, ast_agi_register, (struct ast_module *mod, agi_command *cmd),
37  *                  { return AST_OPTIONAL_API_UNAVAILABLE; });
38  * \endcode
39  *
40  * This defines the 'ast_agi_register' function as an optional API; if a
41  * consumer of this API is loaded when there is no provider of it, then
42  * calling this function will actually call the hidden stub, and return
43  * the value AST_OPTIONAL_API_UNAVAILABLE. This allows the consumer to
44  * safely know that the API is not available, and to avoid using any
45  * other APIs from the not-present provider.
46  *
47  * In addition to this declaration in the header file, the actual definition of
48  * the API function must use the AST_OPTIONAL_API_NAME macro to (possibly)
49  * modify the real name of the API function, depending on the specific
50  * implementation requirements. The corresponding example from res_agi.c:
51  *
52  * \code
53  * int AST_OPTIONAL_API_NAME(ast_agi_register)(struct ast_module *mod, agi_command *cmd)
54  * {
55  * ...
56  * }
57  * \endcode
58  *
59  * In the module providing the API, the AST_OPTIONAL_API macro must
60  * be informed that it should not build the hidden stub function or
61  * apply special aliases to the function prototype; this can be done
62  * by defining AST_API_MODULE just before including the header file
63  * containing the AST_OPTIONAL_API macro calls.
64  */
65
66 /*!
67  * \brief A common value for optional API stub functions to return
68  *
69  * This value is defined as INT_MIN, the minimum value for an integer
70  * (maximum negative value), which can be used by any optional API
71  * functions that return a signed integer value and would not be
72  * able to return such a value under normal circumstances.
73  */
74 #define AST_OPTIONAL_API_UNAVAILABLE    INT_MIN
75
76 /*!
77  * \def AST_OPTIONAL_API_NAME(name)
78  * \brief Expands to the name of the implementation function.
79  */
80
81 /*!
82  * \def AST_OPTIONAL_API(result, name, proto, stub)
83  * \brief Declare an optional API function
84  *
85  * \param result The type of result the function returns
86  * \param name The name of the function
87  * \param proto The prototype (arguments) of the function
88  * \param stub The code block that will be used by the hidden stub when needed
89  *
90  * Example usage:
91  * \code
92  * AST_OPTIONAL_API(int, ast_agi_register, (struct ast_module *mod, agi_command *cmd),
93  *                  { return AST_OPTIONAL_API_UNAVAILABLE; });
94  * \endcode
95  */
96
97 /*!
98  * \def AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub)
99  * \brief Declare an optional API function with compiler attributes
100  *
101  * \param result The type of result the function returns
102  * \param attr Any compiler attributes to be applied to the function (without the __attribute__ wrapper)
103  * \param name The name of the function
104  * \param proto The prototype (arguments) of the function
105  * \param stub The code block that will be used by the hidden stub when needed
106  */
107
108 #if defined(OPTIONAL_API)
109
110 #if !defined(HAVE_ATTRIBUTE_constructor) || !defined(HAVE_ATTRIBUTE_constructor)
111 #error OPTIONAL_API requires compiler constructor/destructor support
112 #endif
113
114 /*!
115  * \internal
116  * \brief Function pointer to an optional API function.
117  *
118  * Functions that are declared as optional may have any signature they want;
119  * they are cast to this type as needed. We don't use a \c void pointer, because
120  * technically data and function pointers are incompatible.
121  *
122  * \note
123  * The may_alias attribute is to avoid type punning/strict aliasing warnings
124  * with older GCC's.
125  */
126 typedef void (*ast_optional_fn)(void) attribute_may_alias;
127
128 /*!
129  * \internal
130  * \brief Provide an implementation of an optional API.
131  *
132  * Any declared usages of this function are linked.
133  *
134  * \param symname Name of the provided function.
135  * \param impl Function pointer to the implementation function.
136  */
137 void ast_optional_api_provide(const char *symname, ast_optional_fn impl);
138
139 /*!
140  * \internal
141  * \brief Remove an implementation of an optional API.
142  *
143  * Any declared usages of this function are unlinked.
144  *
145  * \param symname Name of the provided function.
146  * \param impl Function pointer to the implementation function.
147  */
148 void ast_optional_api_unprovide(const char *symname, ast_optional_fn impl);
149
150 /*!
151  * \internal
152  * \brief Define a usage of an optional API.
153  *
154  * If the API has been provided, it will be linked into \a optional_ref.
155  * Otherwise, it will be linked to \a stub until an implementation is provided.
156  *
157  * \param symname Name of the function to use.
158  * \param optional_ref Pointer-to-function-pointer to link to impl/stub.
159  * \param stub Stub function to link to when impl is not available.
160  * \param module Name of the module requesting the API.
161  */
162 void ast_optional_api_use(const char *symname, ast_optional_fn *optional_ref,
163         ast_optional_fn stub, const char *module);
164
165 /*!
166  * \internal
167  * \brief Remove a usage of an optional API.
168  *
169  * The \a optional_ref will be linked to the \a stub provided at use time,
170  * will no longer be updated if the API is provided/removed.
171  *
172  * \param symname Name of the function to use.
173  * \param optional_ref Pointer-to-function-pointer to link to impl/stub.
174  * \param module Name of the module requesting the API.
175  */
176 void ast_optional_api_unuse(const char *symname, ast_optional_fn *optional_ref,
177         const char *module);
178
179 #define AST_OPTIONAL_API_NAME(name) __##name
180
181 #if defined(AST_API_MODULE)
182 /* Module defining the API */
183
184 #define AST_OPTIONAL_API_IMPL_INIT(name)                                \
185         static void __attribute__((constructor)) __init__##name##_impl(void) { \
186                 ast_optional_api_provide(#name,                         \
187                         (ast_optional_fn)AST_OPTIONAL_API_NAME(name));  \
188         }                                                               \
189         static void __attribute__((destructor)) __dtor__##name##_impl(void) { \
190                 ast_optional_api_unprovide(#name,                       \
191                         (ast_optional_fn)AST_OPTIONAL_API_NAME(name));  \
192         }
193
194 #define AST_OPTIONAL_API(result, name, proto, stub)                     \
195         result AST_OPTIONAL_API_NAME(name) proto;                       \
196         static attribute_unused typeof(AST_OPTIONAL_API_NAME(name)) * const \
197              name = AST_OPTIONAL_API_NAME(name);                        \
198         AST_OPTIONAL_API_IMPL_INIT(name)
199
200 #define AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub)          \
201         result  __attribute__((attr)) AST_OPTIONAL_API_NAME(name) proto; \
202         static attribute_unused typeof(AST_OPTIONAL_API_NAME(name)) * const \
203              name = AST_OPTIONAL_API_NAME(name);                        \
204         AST_OPTIONAL_API_IMPL_INIT(name)
205
206 #else
207 /* Module using the API */
208
209 #define AST_OPTIONAL_API_INIT(name)                                     \
210         static void __attribute__((constructor)) __init__##name(void) { \
211                 ast_optional_api_use(#name, (ast_optional_fn *)&name,   \
212                         (ast_optional_fn)__stub__##name,                \
213                         AST_MODULE);                                    \
214         }                                                               \
215         static void __attribute__((destructor)) __dtor__##name(void) {  \
216                 ast_optional_api_unuse(#name, (ast_optional_fn *)&name, \
217                         AST_MODULE);                                    \
218         }
219
220 #define AST_OPTIONAL_API(result, name, proto, stub)                     \
221         static result __stub__##name proto stub;                        \
222         static attribute_unused                                         \
223                 typeof(__stub__##name) * name;                          \
224         AST_OPTIONAL_API_INIT(name)
225
226 #define AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub)          \
227         static __attribute__((attr)) result __stub__##name proto stub;  \
228         static attribute_unused __attribute__((attr))                   \
229                 typeof(__stub__##name) * name;                          \
230         AST_OPTIONAL_API_INIT(name)
231
232 #endif /* defined(AST_API_MODULE) */
233
234 #else /* defined(OPTIONAL_API) */
235
236 /* Non-optional API */
237
238 #define AST_OPTIONAL_API_NAME(name) name
239
240 #define AST_OPTIONAL_API(result, name, proto, stub)     \
241         result AST_OPTIONAL_API_NAME(name) proto
242
243 #define AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub)  \
244         result __attribute__((attr)) AST_OPTIONAL_API_NAME(name) proto
245
246 #endif /* defined(OPTIONAL_API) */
247
248 #undef AST_API_MODULE
249
250 #endif /* __ASTERISK_OPTIONAL_API_H */