1 /* EINA - EFL data type library 2 * Copyright (C) 2002-2008 Carsten Haitzler, Vincent Torri, 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_TRASH_H__ 20 #define EINA_TRASH_H__ 21 22 /** 23 * @defgroup Eina_Trash_Group Trash 24 * @ingroup Eina_Containers_Group 25 * @brief This group provides a generic container. 26 * 27 * @{ 28 */ 29 30 /** 31 * @typedef Eina_Trash 32 * @brief The type for structure #_Eina_Trash. 33 */ 34 typedef struct _Eina_Trash Eina_Trash; 35 36 /** 37 * @struct _Eina_Trash 38 * @brief The structure type for a generic container of an unused allocated pointer. 39 */ 40 struct _Eina_Trash 41 { 42 Eina_Trash *next; /**< Next item in the trash */ 43 }; 44 45 /** 46 * @brief Initializes a trash before using it. 47 * @details This function just set to zero the trash to correctly 48 * initialize it. 49 * 50 * @param[in] trash The trash 51 * 52 * @note You can just set *trash to @c NULL and you will have 53 * the same result. 54 */ 55 static inline void eina_trash_init(Eina_Trash **trash) EINA_ARG_NONNULL(1); 56 57 /** 58 * @brief Pushes an unused pointer in the trash instead of freeing it. 59 * @details Instead of freeing a pointer and put pressure on malloc/free 60 * you can push it in a trash for a later use. This function just 61 * provide a fast way to push a now unused pointer into a trash. 62 * 63 * @param[in,out] trash A pointer to an Eina_Trash 64 * @param[in] data An unused pointer big enough to put a (void*) 65 * 66 * @note Do not use the pointer after insertion or bad things will 67 * happens. 68 * 69 * @note This trash will not resize, nor do anything with the size of 70 * the region pointed by @p data, so it's your duty to manage the size. 71 */ 72 static inline void eina_trash_push(Eina_Trash **trash, void *data) EINA_ARG_NONNULL(1); 73 74 /** 75 * @brief Pops an available pointer from the trash if possible. 76 * @details Instead of calling malloc, and putting pressure on malloc/free 77 * you can recycle the content of the trash, if it's not empty. 78 * 79 * @param[in] trash A #Eina_Trash handle 80 * 81 * @note This trash will not resize, nor do anything with the size of 82 * the region pointed by pointer inside the trash, so it's your duty 83 * to manage the size of the returned pointer. 84 */ 85 static inline void *eina_trash_pop(Eina_Trash **trash) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 86 87 /** 88 * @def EINA_TRASH_CLEAN 89 * @brief Definition for a macro to remove all the pointers from the trash. 90 * @details This macro allows the cleaning of @a trash in an easy way. It 91 * removes all the pointers from @a trash until it's empty. 92 * 93 * @param[in,out] trash The trash to clean 94 * @param[out] data The pointer extracted from the trash 95 * 96 * @note This macro can be used for freeing the data in the trash, like in 97 * the following example: 98 * 99 * @code 100 * Eina_Trash *trash = NULL; 101 * char *data; 102 * 103 * // trash is filled with a pointer to some duped strings. 104 * 105 * EINA_TRASH_CLEAN(&trash, data) 106 * free(data); 107 * @endcode 108 * 109 * @note This macro is useful when you implement some memory pool. 110 */ 111 #define EINA_TRASH_CLEAN(trash, data) while ((data = eina_trash_pop(trash))) 112 113 #include "eina_inline_trash.x" 114 115 /** 116 * @} 117 */ 118 119 #endif /* EINA_TRASH_H_ */ 120