diff options
Diffstat (limited to '')
-rw-r--r-- | libraries/eina/src/include/eina_module.h | 350 |
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 | */ | ||
68 | typedef struct _Eina_Module Eina_Module; | ||
69 | |||
70 | /** | ||
71 | * @typedef Eina_Module_Cb | ||
72 | * Dynamic module loader callback. | ||
73 | */ | ||
74 | typedef 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 | */ | ||
84 | typedef 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 | */ | ||
92 | typedef 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 | */ | ||
113 | extern 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 | */ | ||
119 | extern 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 | */ | ||
136 | EAPI 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 | */ | ||
150 | EAPI 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 | */ | ||
173 | EAPI 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 | */ | ||
190 | EAPI 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 | */ | ||
205 | EAPI 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 | */ | ||
218 | EAPI 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 | */ | ||
236 | EAPI 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 | */ | ||
253 | EAPI 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 | */ | ||
270 | EAPI 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 | */ | ||
292 | EAPI 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 | */ | ||
303 | EAPI 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 | */ | ||
314 | EAPI 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 | */ | ||
325 | EAPI 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 | */ | ||
339 | EAPI 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_*/ | ||