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 */