aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/eina/src/include/eina_module.h
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/eina/src/include/eina_module.h')
-rw-r--r--libraries/eina/src/include/eina_module.h350
1 files changed, 0 insertions, 350 deletions
diff --git a/libraries/eina/src/include/eina_module.h b/libraries/eina/src/include/eina_module.h
deleted file mode 100644
index 178fa9a..0000000
--- a/libraries/eina/src/include/eina_module.h
+++ /dev/null
@@ -1,350 +0,0 @@
1/* EINA - EFL data type library
2 * Copyright (C) 2007-2008 Jorge Luis Zapata Muga
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library;
16 * if not, see <http://www.gnu.org/licenses/>.
17 */
18
19#ifndef EINA_MODULE_H_
20#define EINA_MODULE_H_
21
22#include "eina_types.h"
23#include "eina_array.h"
24#include "eina_error.h"
25
26/**
27 * @addtogroup Eina_Module_Group Module
28 *
29 * @brief These functions provide module management.
30 */
31
32/**
33 * @addtogroup Eina_Tools_Group Tools
34 *
35 * @{
36 */
37
38/**
39 * @defgroup Eina_Module_Group Module
40 *
41 * Eina module provides some helpers over POSIX dlopen(). It is not
42 * meant to replace, abstract or make a "portable" version of the
43 * POSIX, but enhance its usage by defining some good practices.
44 *
45 * Modules are created with eina_module_new() and later loaded with
46 * eina_module_load(). Loads are reference counted and there must be
47 * the same number of eina_module_unload() in order to have it to call
48 * dlclose(). This makes simple to have different users for the same
49 * module.
50 *
51 * The loaded shared objects may have two visible functions that will
52 * be called and might provide initialization and shutdown
53 * proceedures. The symbols are @c __eina_module_init and
54 * @c __eina_module_shutdown and will be defined by the macros
55 * EINA_MODULE_INIT() and EINA_MODULE_SHUTDOWN().
56 *
57 * There are some helpers to automatically create modules based on
58 * directory listing. See eina_module_arch_list_get(),
59 * eina_module_list_get() and eina_module_find().
60 *
61 * @{
62 */
63
64/**
65 * @typedef Eina_Module
66 * Dynamic module loader handle.
67 */
68typedef struct _Eina_Module Eina_Module;
69
70/**
71 * @typedef Eina_Module_Cb
72 * Dynamic module loader callback.
73 */
74typedef Eina_Bool (*Eina_Module_Cb)(Eina_Module *m, void *data);
75
76/**
77 * @typedef Eina_Module_Init
78 * If a function with such signature is exported by module as
79 * __eina_module_init, it will be called on the first load after
80 * dlopen() and if #EINA_FALSE is returned, load will fail, #EINA_TRUE
81 * means the module was successfully initialized.
82 * @see Eina_Module_Shutdown
83 */
84typedef Eina_Bool (*Eina_Module_Init)(void);
85
86/**
87 * @typedef Eina_Module_Shutdown
88 * If a function with such signature is exported by module as
89 * __eina_module_shutdown, it will be called before calling dlclose()
90 * @see Eina_Module_Init
91 */
92typedef void (*Eina_Module_Shutdown)(void);
93
94/**
95 * @def EINA_MODULE_INIT
96 * declares the given function as the module initializer (__eina_module_init).
97 * It must be of signature #Eina_Module_Init
98 */
99#define EINA_MODULE_INIT(f) EAPI Eina_Module_Init __eina_module_init = &f
100
101/**
102 * @def EINA_MODULE_SHUTDOWN
103 * declares the given function as the module shutdownializer
104 * (__eina_module_shutdown). It must be of signature
105 * #Eina_Module_Shutdown
106 */
107#define EINA_MODULE_SHUTDOWN(f) EAPI Eina_Module_Shutdown __eina_module_shutdown = &f
108
109/**
110 * @var EINA_ERROR_WRONG_MODULE
111 * Error identifier corresponding to a wrong module.
112 */
113extern EAPI Eina_Error EINA_ERROR_WRONG_MODULE;
114
115/**
116 * @var EINA_ERROR_MODULE_INIT_FAILED
117 * Error identifier corresponding to a failure during the initialisation of a module.
118 */
119extern EAPI Eina_Error EINA_ERROR_MODULE_INIT_FAILED;
120
121/**
122 * @brief Return a new module.
123 *
124 * @param file The name of the file module to load.
125 *
126 * This function returns a new module. If @p file is @c NULL, the
127 * function returns @c NULL, otherwise, it allocates an Eina_Module,
128 * stores a duplicate string of @p file, sets its reference to @c 0
129 * and its handle to @c NULL.
130 *
131 * When the new module is not needed anymore, use eina_module_free()
132 * to free the allocated memory.
133 *
134 * @see eina_module_load
135 */
136EAPI Eina_Module *
137 eina_module_new(const char *file) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
138
139/**
140 * @brief Delete a module.
141 *
142 * @param module The module to delete.
143 * @return EINA_TRUE on success, EINA_FALSE otherwise.
144 *
145 * This function calls eina_module_unload() if @p module has been previously
146 * loaded and frees the allocated memory. On success this function
147 * returns EINA_TRUE and EINA_FALSE otherwise. If @p module is @c NULL, the
148 * function returns immediately.
149 */
150EAPI Eina_Bool
151 eina_module_free(Eina_Module *module) EINA_ARG_NONNULL(1);
152
153/**
154 * @brief Load a module.
155 *
156 * @param module The module to load.
157 * @return EINA_TRUE on success, EINA_FALSE otherwise.
158 *
159 * This function load the shared file object passed in
160 * eina_module_new(). If it is a internal Eina module (like the
161 * mempools), it also initialize it. It the shared file object can not
162 * be loaded, the error #EINA_ERROR_WRONG_MODULE is set and
163 * #EINA_FALSE is returned. If it is a internal Eina module and the
164 * module can not be initialized, the error
165 * #EINA_ERROR_MODULE_INIT_FAILED is set and #EINA_FALSE is
166 * returned. If the module has already been loaded, it's refeence
167 * counter is increased by one and #EINA_TRUE is returned. If @p module is
168 * @c NULL, the function returns immediately #EINA_FALSE.
169 *
170 * When the symbols of the shared file objetcts are not needed
171 * anymore, call eina_module_unload() to unload the module.
172 */
173EAPI Eina_Bool
174 eina_module_load(Eina_Module *module) EINA_ARG_NONNULL(1);
175
176/**
177 * @brief Unload a module.
178 *
179 * @param module The module to load.
180 * @return EINA_TRUE on success, EINA_FALSE otherwise.
181 *
182 * This function unload the module @p module that has been previously
183 * loaded by eina_module_load(). If the reference counter of @p module is
184 * strictly greater than @c 1, #EINA_FALSE is returned. Otherwise, the
185 * shared object file is closed and if it is a internal Eina module, it
186 * is shutted down just before. In that case, #EINA_TRUE is
187 * returned. In all case, the reference counter is decreased. If @p module
188 * is @c NULL, the function returns immediately #EINA_FALSE.
189 */
190EAPI Eina_Bool
191 eina_module_unload(Eina_Module *module) EINA_ARG_NONNULL(1);
192
193/**
194 * @brief Retrive the data associated to a symbol.
195 *
196 * @param module The module.
197 * @param symbol The symbol.
198 * @return The data associated to the symbol, or @c NULL on failure.
199 *
200 * This function returns the data associated to @p symbol of @p module. @p
201 * module must have been loaded before with eina_module_load(). If @p module
202 * is @c NULL, or if it has not been correctly loaded before, the
203 * function returns immediately @c NULL.
204 */
205EAPI void *
206 eina_module_symbol_get(const Eina_Module *module, const char *symbol) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
207
208/**
209 * @brief Return the file name associated to the module.
210 *
211 * @param module The module.
212 * @return The file name.
213 *
214 * This function returns the file name passed in eina_module_new(). If
215 * @p module is @c NULL, the function returns immediately @c NULL. The
216 * returned value must no be freed.
217 */
218EAPI const char *
219 eina_module_file_get(const Eina_Module *module) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
220
221
222/**
223 * @brief Return the path built from the location of a library and a
224 * given sub directory.
225 *
226 * @param symbol The symbol to search for.
227 * @param sub_dir The subdirectory to append.
228 * @return The built path on success, @c NULL otherwise.
229 *
230 * This function returns the path built by concatenating the path of
231 * the library containing the symbol @p symbol and @p sub_dir. @p sub_dir
232 * can be @c NULL. The returned path must be freed when not used
233 * anymore. If the symbol is not found, or dl_addr() is not supported,
234 * or allocation fails, this function returns @c NULL.
235 */
236EAPI char *
237 eina_module_symbol_path_get(const void *symbol, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2);
238
239/**
240 * @brief Return the path built from the value of an environment varialbe and a
241 * given sub directory.
242 *
243 * @param env The environment variable to expand.
244 * @param sub_dir The subdirectory to append.
245 * @return The built path on success, @c NULL otherwise.
246 *
247 * This function returns the path built by concatenating the value of
248 * the environment variable named @p env and @p sub_dir. @p sub_dir
249 * can be @c NULL. The returned path must be freed when not used
250 * anymore. If the symbol is not found, or @p env does not exist, or
251 * allocation fails, this function returns @c NULL.
252 */
253EAPI char *
254 eina_module_environment_path_get(const char *env, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2);
255
256
257/**
258 * @brief Get an array of modules found on the directory path matching an arch type.
259 *
260 * @param array The array that stores the list of the modules.
261 * @param path The directory's path to search for modules.
262 * @param arch The architecture string.
263 * @return The array of modules found in @p path matching @p arch.
264 *
265 * This function adds to @p array the module names found in @p path
266 * which match the cpu architecture @p arch. If @p path or @p arch is
267 * @c NULL, the function returns immediately @p array. @p array can be
268 * @c NULL. In that case, it is created with 4 elements.
269 */
270EAPI Eina_Array *
271 eina_module_arch_list_get(Eina_Array *array, const char *path, const char *arch);
272
273/**
274 * @brief Get a list of modules found on the directory path.
275 *
276 * @param array The array that stores the list of the modules.
277 * @param path The directory's path to search for modules.
278 * @param recursive Iterate recursively on the path.
279 * @param cb Callback function to call on each module.
280 * @param data Data passed to the callback function.
281 * @return The array of modules found in @p path.
282 *
283 * This function adds to @p array the list of modules found in
284 * @p path. If @p recursive is #EINA_TRUE, then recursive search is
285 * done. The callback @p cb is called on each module found, and @p data
286 * is passed to @p cb. If @p path is @c NULL, the function returns
287 * immediately @p array. If the returned value of @p cb is 0, the
288 * module will not be added to the list, otherwise it will be added.
289 * @p array can be @c NULL. In that case, it is created with 4
290 * elements. @p cb can be @c NULL.
291 */
292EAPI Eina_Array *
293 eina_module_list_get(Eina_Array *array, const char *path, Eina_Bool recursive, Eina_Module_Cb cb, void *data) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
294
295/**
296 * @brief Load every module on the list of modules.
297 *
298 * @param array The array of modules to load.
299 *
300 * This function calls eina_module_load() on each element found in
301 * @p array. If @p array is @c NULL, this function does nothing.
302 */
303EAPI void
304 eina_module_list_load(Eina_Array *array) EINA_ARG_NONNULL(1);
305
306/**
307 * @brief Unload every module on the list of modules.
308 *
309 * @param array The array of modules to unload.
310 *
311 * This function calls eina_module_unload() on each element found in
312 * @p array. If @p array is @c NULL, this function does nothing.
313 */
314EAPI void
315 eina_module_list_unload(Eina_Array *array) EINA_ARG_NONNULL(1);
316
317/**
318 * @p Free every module on the list of modules.
319 *
320 * @param array The array of modules to free.
321 *
322 * This function calls eina_module_free() on each element found in
323 * @p array. If @p array is @c NULL, this function does nothing.
324 */
325EAPI void
326 eina_module_list_free(Eina_Array *array) EINA_ARG_NONNULL(1);
327
328/**
329 * @brief Find an module in array.
330 *
331 * @param array The array to find the module.
332 * @param module The name of module to be searched.
333 * @return The module to find on success, @c NULL otherwise.
334 *
335 * This function finds an @p module in @p array.
336 * If the element is found the function returns the module, else
337 * @c NULL is returned.
338 */
339EAPI Eina_Module *
340 eina_module_find(const Eina_Array *array, const char *module) EINA_ARG_NONNULL(1, 2);
341
342/**
343 * @}
344 */
345
346/**
347 * @}
348 */
349
350#endif /*EINA_MODULE_H_*/