Logger/CLI/etc.: Fix some aesthetic issues; reduce chatty verbose messages
[asterisk/asterisk.git] / main / optional_api.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013, Digium, Inc.
5  *
6  * David M. Lee, II <dlee@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 #include "asterisk.h"
20
21 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
22
23 #include "asterisk/optional_api.h"
24 #include "asterisk/utils.h"
25
26 #if defined(OPTIONAL_API)
27
28 /*
29  * \file Optional API innards.
30  *
31  * The calls to ast_optional_api_*() happen implicitly from \c __constructor__
32  * calls which are defined in header files. This means that some number of them
33  * happen before main() is called. This makes calling most Asterisk APIs
34  * dangerous, since we could be called before they are initialized. This
35  * includes things like AO2, malloc debug, and static mutexes.
36  *
37  * Another limitation is that most functions are called from the midst of
38  * dlopen() or dlclose(), and there is no opportunity to return a failure code.
39  * The best we can do is log an error, and call ast_do_crash().
40  *
41  * Fortunately, there are some constraints that help us out. The \c
42  * ast_optional_api_*() are called during module loads, which happens either
43  * before main(), or during dlopen() calls. These are already serialized, so we
44  * don't have to lock ourselves.
45  */
46
47 /*! \brief A user of an optional API */
48 struct optional_api_user {
49         /*! Pointer to function pointer to link */
50         ast_optional_fn *optional_ref;
51         /*! Stub to use when impl is unavailable */
52         ast_optional_fn stub;
53         /*! Name of the module using the API */
54         char module[];
55 };
56
57 /*! \brief An optional API */
58 struct optional_api {
59         /*! Pointer to the implementation function; could be null */
60         ast_optional_fn impl;
61         /*! Variable length array of users of this API */
62         struct optional_api_user **users;
63         /*! Allocated size of the \a users array */
64         size_t users_maxlen;
65         /*! Number of entries in the \a users array */
66         size_t users_len;
67         /*! Name of the optional API function */
68         char symname[];
69 };
70
71 /*!
72  * \brief Free an \ref optional_api_user.
73  *
74  * \param user User struct to free.
75  */
76 static void optional_api_user_destroy(struct optional_api_user *user)
77 {
78         *user->optional_ref = user->stub;
79         ast_std_free(user);
80 }
81
82 /*!
83  * \brief Create an \ref optional_api_user.
84  *
85  * \param optional_ref Pointer-to-function-pointer to link to impl/stub.
86  * \param stub Stub function to link to when impl is not available.
87  * \param module Name of the module requesting the API.
88  *
89  * \return New \ref optional_api_user.
90  * \return \c NULL on error.
91  */
92 static struct optional_api_user *optional_api_user_create(
93         ast_optional_fn *optional_ref, ast_optional_fn stub, const char *module)
94 {
95         struct optional_api_user *user;
96         size_t size = sizeof(*user) + strlen(module) + 1;
97
98         user = ast_std_calloc(1, size);
99         if (!user) {
100                 return NULL;
101         }
102
103         user->optional_ref = optional_ref;
104         user->stub = stub;
105         strcpy(user->module, module); /* SAFE */
106
107         return user;
108 }
109
110 /*!
111  * \brief Free an \ref optional_api.
112  *
113  * \param api API struct to free.
114  */
115 static void optional_api_destroy(struct optional_api *api)
116 {
117         while (api->users_len--) {
118                 optional_api_user_destroy(api->users[api->users_len]);
119         }
120         ast_std_free(api->users);
121         api->users = NULL;
122         api->users_maxlen = 0;
123         ast_std_free(api);
124 }
125
126 /*!
127  * \brief Create an \ref optional_api.
128  *
129  * \param symname Name of the optional function.
130  * \return New \ref optional_api.
131  * \return \c NULL on error.
132  */
133 static struct optional_api *optional_api_create(const char *symname)
134 {
135         struct optional_api *api;
136         size_t size;
137
138         size = sizeof(*api) + strlen(symname) + 1;
139         api = ast_std_calloc(1, size);
140         if (!api) {
141                 ast_log(LOG_ERROR, "Failed to allocate api\n");
142                 return NULL;
143         }
144
145         strcpy(api->symname, symname); /* SAFE */
146
147         return api;
148 }
149
150 /*! Array of \ref optional_api functions */
151 struct {
152         /*! Variable length array of API's */
153         struct optional_api **list;
154         /*! Allocated size of the \a list array */
155         size_t maxlen;
156         /*! Number of entries in the \a list array */
157         size_t len;
158 } apis;
159
160 /*!
161  * \brief Gets (or creates) the \ref optional_api for the given function.
162  *
163  * \param sysname Name of the function to look up.
164  * \return Corresponding \ref optional_api.
165  * \return \c NULL on error.
166  */
167 static struct optional_api *get_api(const char *symname)
168 {
169         struct optional_api *api;
170         size_t i;
171
172         /* Find one, if we already have it */
173         if (apis.list) {
174                 for (i = 0; i < apis.len; ++i) {
175                         if (strcmp(symname, apis.list[i]->symname) == 0) {
176                                 return apis.list[i];
177                         }
178                 }
179         }
180
181         /* API not found. Build one */
182         api = optional_api_create(symname);
183         if (!api) {
184                 return NULL;
185         }
186
187         /* Grow the list, if needed */
188         if (apis.len + 1 > apis.maxlen) {
189                 size_t new_maxlen = apis.maxlen ? 2 * apis.maxlen : 1;
190                 struct optional_api **new_list;
191
192                 new_list = ast_std_realloc(apis.list, new_maxlen * sizeof(*new_list));
193                 if (!new_list) {
194                         optional_api_destroy(api);
195                         ast_log(LOG_ERROR, "Failed to allocate api list\n");
196                         return NULL;
197                 }
198
199                 apis.maxlen = new_maxlen;
200                 apis.list = new_list;
201         }
202
203         apis.list[apis.len++] = api;
204
205         return api;
206 }
207
208 /*!
209  * \brief Re-links a given \a user against its associated \a api.
210  *
211  * If the \a api has an implementation, the \a user is linked to that
212  * implementation. Otherwise, the \a user is linked to its \a stub.
213  *
214  * \param user \ref optional_api_user to link.
215  * \param api \ref optional_api to link.
216  */
217 static void optional_api_user_relink(struct optional_api_user *user,
218         struct optional_api *api)
219 {
220         if (api->impl && *user->optional_ref != api->impl) {
221                 *user->optional_ref = api->impl;
222         } else if (!api->impl && *user->optional_ref != user->stub) {
223                 *user->optional_ref = user->stub;
224         }
225 }
226
227 /*!
228  * \brief Sets the implementation function pointer for an \a api.
229  *
230  * \param api API to implement/stub out.
231  * \param impl Pointer to implementation function. Can be 0 to remove
232  *             implementation.
233  */
234 static void optional_api_set_impl(struct optional_api *api,
235         ast_optional_fn impl)
236 {
237         size_t i;
238
239         api->impl = impl;
240
241         /* re-link all users */
242         for (i = 0; i < api->users_len; ++i) {
243                 optional_api_user_relink(api->users[i], api);
244         }
245 }
246
247 void ast_optional_api_provide(const char *symname, ast_optional_fn impl)
248 {
249         struct optional_api *api;
250
251         api = get_api(symname);
252         if (!api) {
253                 ast_log(LOG_ERROR, "%s: Allocation failed\n", symname);
254                 ast_do_crash();
255                 return;
256         }
257
258         optional_api_set_impl(api, impl);
259 }
260
261 void ast_optional_api_unprovide(const char *symname, ast_optional_fn impl)
262 {
263         struct optional_api *api;
264
265         api = get_api(symname);
266         if (!api) {
267                 ast_log(LOG_ERROR, "%s: Could not find api\n", symname);
268                 ast_do_crash();
269                 return;
270         }
271
272         optional_api_set_impl(api, 0);
273 }
274
275 void ast_optional_api_use(const char *symname, ast_optional_fn *optional_ref,
276         ast_optional_fn stub, const char *module)
277 {
278         struct optional_api_user *user;
279         struct optional_api *api;
280
281
282         api = get_api(symname);
283         if (!api) {
284                 ast_log(LOG_ERROR, "%s: Allocation failed\n", symname);
285                 ast_do_crash();
286                 return;
287         }
288
289         user = optional_api_user_create(optional_ref, stub, module);
290         if (!user) {
291                 ast_log(LOG_ERROR, "%s: Allocation failed\n", symname);
292                 ast_do_crash();
293                 return;
294         }
295
296         /* Add user to the API */
297         if (api->users_len + 1 > api->users_maxlen) {
298                 size_t new_maxlen = api->users_maxlen ? 2 * api->users_maxlen : 1;
299                 struct optional_api_user **new_list;
300
301                 new_list = ast_std_realloc(api->users, new_maxlen * sizeof(*new_list));
302                 if (!new_list) {
303                         optional_api_user_destroy(user);
304                         ast_log(LOG_ERROR, "Failed to allocate api list\n");
305                         ast_do_crash();
306                         return;
307                 }
308
309                 api->users_maxlen = new_maxlen;
310                 api->users = new_list;
311         }
312
313         api->users[api->users_len++] = user;
314
315         optional_api_user_relink(user, api);
316 }
317
318 void ast_optional_api_unuse(const char *symname, ast_optional_fn *optional_ref,
319         const char *module)
320 {
321         struct optional_api *api;
322         size_t i;
323
324         api = get_api(symname);
325         if (!api) {
326                 ast_log(LOG_ERROR, "%s: Could not find api\n", symname);
327                 ast_do_crash();
328                 return;
329         }
330
331         for (i = 0; i < api->users_len; ++i) {
332                 struct optional_api_user *user = api->users[i];
333
334                 if (user->optional_ref == optional_ref) {
335                         if (*user->optional_ref != user->stub) {
336                                 *user->optional_ref = user->stub;
337                         }
338
339                         /* Remove from the list */
340                         api->users[i] = api->users[--api->users_len];
341
342                         optional_api_user_destroy(user);
343                         return;
344                 }
345         }
346
347         ast_log(LOG_ERROR, "%s: Could not find user %s\n", symname, module);
348 }
349
350 #endif /* defined(OPTIONAL_API) */