git migration: Refactor the ASTERISK_FILE_VERSION macro
[asterisk/asterisk.git] / main / astobj2_container_private.h
1 /*
2  * astobj2 - replacement containers for asterisk data structures.
3  *
4  * Copyright (C) 2006 Marta Carbone, Luigi Rizzo - Univ. di Pisa, Italy
5  *
6  * See http://www.asterisk.org for more information about
7  * the Asterisk project. Please do not directly contact
8  * any of the maintainers of this project for assistance;
9  * the project provides a web site, mailing lists and IRC
10  * channels for your use.
11  *
12  * This program is free software, distributed under the terms of
13  * the GNU General Public License Version 2. See the LICENSE file
14  * at the top of the source tree.
15  */
16
17 /*! \file
18  *
19  * \brief Common, private definitions for astobj2 containers.
20  *
21  * \author Richard Mudgett <rmudgett@digium.com>
22  */
23
24 #ifndef ASTOBJ2_CONTAINER_PRIVATE_H_
25 #define ASTOBJ2_CONTAINER_PRIVATE_H_
26
27 #include "asterisk/astobj2.h"
28
29 /*!
30  * \internal
31  * \brief Enum for internal_ao2_unlink_node.
32  */
33 enum ao2_unlink_node_flags {
34         /*! Remove the node from the object's weak link list
35          * OR unref the object if it's a strong reference. */
36         AO2_UNLINK_NODE_UNLINK_OBJECT = (1 << 0),
37         /*! Modified unlink_object to skip the unref of the object. */
38         AO2_UNLINK_NODE_NOUNREF_OBJECT = (1 << 1),
39         /*! Unref the node. */
40         AO2_UNLINK_NODE_UNREF_NODE = (1 << 2),
41         /*! Decrement the container's element count. */
42         AO2_UNLINK_NODE_DEC_COUNT = (1 << 3),
43 };
44
45 enum ao2_callback_type {
46         AO2_CALLBACK_DEFAULT,
47         AO2_CALLBACK_WITH_DATA,
48 };
49
50 enum ao2_container_insert {
51         /*! The node was inserted into the container. */
52         AO2_CONTAINER_INSERT_NODE_INSERTED,
53         /*! The node object replaced an existing node object. */
54         AO2_CONTAINER_INSERT_NODE_OBJ_REPLACED,
55         /*! The node was rejected (duplicate). */
56         AO2_CONTAINER_INSERT_NODE_REJECTED,
57 };
58
59 /*! Allow enough room for container specific traversal state structs */
60 #define AO2_TRAVERSAL_STATE_SIZE        100
61
62 /*!
63  * \brief Generic container node.
64  *
65  * \details This is the base container node type that contains
66  * values common to all container nodes.
67  */
68 struct ao2_container_node {
69         /*! Stored object in node. */
70         void *obj;
71         /*! Container holding the node.  (Does not hold a reference.) */
72         struct ao2_container *my_container;
73         /*! TRUE if the node is linked into the container. */
74         unsigned int is_linked:1;
75 };
76
77 /*!
78  * \brief Destroy this container.
79  *
80  * \param self Container to operate upon.
81  *
82  * \return Nothing
83  */
84 typedef void (*ao2_container_destroy_fn)(struct ao2_container *self);
85
86 /*!
87  * \brief Create an empty copy of this container.
88  *
89  * \param self Container to operate upon.
90  *
91  * \retval empty-container on success.
92  * \retval NULL on error.
93  */
94 typedef struct ao2_container *(*ao2_container_alloc_empty_clone_fn)(struct ao2_container *self);
95
96 /*!
97  * \brief Create an empty copy of this container. (Debug version)
98  *
99  * \param self Container to operate upon.
100  * \param tag used for debugging.
101  * \param file Debug file name invoked from
102  * \param line Debug line invoked from
103  * \param func Debug function name invoked from
104  * \param ref_debug TRUE if to output a debug reference message.
105  *
106  * \retval empty-container on success.
107  * \retval NULL on error.
108  */
109 typedef struct ao2_container *(*ao2_container_alloc_empty_clone_debug_fn)(struct ao2_container *self, const char *tag, const char *file, int line, const char *func, int ref_debug);
110
111 /*!
112  * \brief Create a new container node.
113  *
114  * \param self Container to operate upon.
115  * \param obj_new Object to put into the node.
116  * \param tag used for debugging.
117  * \param file Debug file name invoked from
118  * \param line Debug line invoked from
119  * \param func Debug function name invoked from
120  *
121  * \retval initialized-node on success.
122  * \retval NULL on error.
123  */
124 typedef struct ao2_container_node *(*ao2_container_new_node_fn)(struct ao2_container *self, void *obj_new, const char *tag, const char *file, int line, const char *func);
125
126 /*!
127  * \brief Insert a node into this container.
128  *
129  * \param self Container to operate upon.
130  * \param node Container node to insert into the container.
131  *
132  * \return enum ao2_container_insert value.
133  */
134 typedef enum ao2_container_insert (*ao2_container_insert_fn)(struct ao2_container *self, struct ao2_container_node *node);
135
136 /*!
137  * \brief Find the first container node in a traversal.
138  *
139  * \param self Container to operate upon.
140  * \param flags search_flags to control traversing the container
141  * \param arg Comparison callback arg parameter.
142  * \param v_state Traversal state to restart container traversal.
143  *
144  * \retval node-ptr of found node (Reffed).
145  * \retval NULL when no node found.
146  */
147 typedef struct ao2_container_node *(*ao2_container_find_first_fn)(struct ao2_container *self, enum search_flags flags, void *arg, void *v_state);
148
149 /*!
150  * \brief Find the next container node in a traversal.
151  *
152  * \param self Container to operate upon.
153  * \param v_state Traversal state to restart container traversal.
154  * \param prev Previous node returned by the traversal search functions.
155  *    The ref ownership is passed back to this function.
156  *
157  * \retval node-ptr of found node (Reffed).
158  * \retval NULL when no node found.
159  */
160 typedef struct ao2_container_node *(*ao2_container_find_next_fn)(struct ao2_container *self, void *v_state, struct ao2_container_node *prev);
161
162 /*!
163  * \brief Cleanup the container traversal state.
164  *
165  * \param v_state Traversal state to cleanup.
166  *
167  * \return Nothing
168  */
169 typedef void (*ao2_container_find_cleanup_fn)(void *v_state);
170
171 /*!
172  * \brief Find the next non-empty iteration node in the container.
173  *
174  * \param self Container to operate upon.
175  * \param prev Previous node returned by the iterator.
176  * \param flags search_flags to control iterating the container.
177  *   Only AO2_ITERATOR_DESCENDING is useful by the method.
178  *
179  * \note The container is already locked.
180  *
181  * \retval node on success.
182  * \retval NULL on error or no more nodes in the container.
183  */
184 typedef struct ao2_container_node *(*ao2_iterator_next_fn)(struct ao2_container *self, struct ao2_container_node *prev, enum ao2_iterator_flags flags);
185
186 /*!
187  * \brief Display contents of the specified container.
188  *
189  * \param self Container to dump.
190  * \param where User data needed by prnt to determine where to put output.
191  * \param prnt Print output callback function to use.
192  * \param prnt_obj Callback function to print the given object's key. (NULL if not available)
193  *
194  * \return Nothing
195  */
196 typedef void (*ao2_container_display)(struct ao2_container *self, void *where, ao2_prnt_fn *prnt, ao2_prnt_obj_fn *prnt_obj);
197
198 /*!
199  * \brief Display statistics of the specified container.
200  *
201  * \param self Container to display statistics.
202  * \param where User data needed by prnt to determine where to put output.
203  * \param prnt Print output callback function to use.
204  *
205  * \note The container is already locked for reading.
206  *
207  * \return Nothing
208  */
209 typedef void (*ao2_container_statistics)(struct ao2_container *self, void *where, ao2_prnt_fn *prnt);
210
211 /*!
212  * \brief Perform an integrity check on the specified container.
213  *
214  * \param self Container to check integrity.
215  *
216  * \note The container is already locked for reading.
217  *
218  * \retval 0 on success.
219  * \retval -1 on error.
220  */
221 typedef int (*ao2_container_integrity)(struct ao2_container *self);
222
223 /*!
224  * \internal
225  * \brief Increment the container linked object statistic.
226  * \since 12.4.0
227  *
228  * \param container Container to operate upon.
229  * \param node Container node linking object to.
230  *
231  * \return Nothing
232  */
233 typedef void (*ao2_link_node_stat_fn)(struct ao2_container *container, struct ao2_container_node *node);
234
235 /*!
236  * \internal
237  * \brief Decrement the container linked object statistic.
238  * \since 12.4.0
239  *
240  * \param container Container to operate upon.
241  * \param node Container node unlinking object from.
242  *
243  * \return Nothing
244  */
245 typedef void (*ao2_unlink_node_stat_fn)(struct ao2_container *container, struct ao2_container_node *node);
246
247 /*! Container virtual methods template. */
248 struct ao2_container_methods {
249         /*! Destroy this container. */
250         ao2_container_destroy_fn destroy;
251         /*! \brief Create an empty copy of this container. */
252         ao2_container_alloc_empty_clone_fn alloc_empty_clone;
253         /*! \brief Create an empty copy of this container. (Debug version) */
254         ao2_container_alloc_empty_clone_debug_fn alloc_empty_clone_debug;
255         /*! Create a new container node. */
256         ao2_container_new_node_fn new_node;
257         /*! Insert a node into this container. */
258         ao2_container_insert_fn insert;
259         /*! Traverse the container, find the first node. */
260         ao2_container_find_first_fn traverse_first;
261         /*! Traverse the container, find the next node. */
262         ao2_container_find_next_fn traverse_next;
263         /*! Traverse the container, cleanup state. */
264         ao2_container_find_cleanup_fn traverse_cleanup;
265         /*! Find the next iteration element in the container. */
266         ao2_iterator_next_fn iterator_next;
267 #if defined(AO2_DEBUG)
268         /*! Increment the container linked object statistic. */
269         ao2_link_node_stat_fn link_stat;
270         /*! Deccrement the container linked object statistic. */
271         ao2_unlink_node_stat_fn unlink_stat;
272         /*! Display container contents. (Method for debug purposes) */
273         ao2_container_display dump;
274         /*! Display container debug statistics. (Method for debug purposes) */
275         ao2_container_statistics stats;
276         /*! Perform an integrity check on the container. (Method for debug purposes) */
277         ao2_container_integrity integrity;
278 #endif  /* defined(AO2_DEBUG) */
279 };
280
281 /*!
282  * \brief Generic container type.
283  *
284  * \details This is the base container type that contains values
285  * common to all container types.
286  *
287  * \todo Linking and unlinking container objects is typically
288  * expensive, as it involves a malloc()/free() of a small object
289  * which is very inefficient.  To optimize this, we can allocate
290  * larger arrays of container nodes when we run out of them, and
291  * then manage our own freelist.  This will be more efficient as
292  * we can do the freelist management while we hold the lock
293  * (that we need anyway).
294  */
295 struct ao2_container {
296         /*! Container virtual method table. */
297         const struct ao2_container_methods *v_table;
298         /*! Container sort function if the container is sorted. */
299         ao2_sort_fn *sort_fn;
300         /*! Container traversal matching function for ao2_find. */
301         ao2_callback_fn *cmp_fn;
302         /*! The container option flags */
303         uint32_t options;
304         /*! Number of elements in the container. */
305         int elements;
306 #if defined(AO2_DEBUG)
307         /*! Number of nodes in the container. */
308         int nodes;
309         /*! Maximum number of empty nodes in the container. (nodes - elements) */
310         int max_empty_nodes;
311 #endif  /* defined(AO2_DEBUG) */
312         /*!
313          * \brief TRUE if the container is being destroyed.
314          *
315          * \note The destruction traversal should override any requested
316          * search order to do the most efficient order for destruction.
317          *
318          * \note There should not be any empty nodes in the container
319          * during destruction.  If there are then an error needs to be
320          * issued about container node reference leaks.
321          */
322         unsigned int destroying:1;
323 };
324
325 /*!
326  * \internal
327  * \brief Unlink a node from this container.
328  *
329  * \param node Node to operate upon.
330  * \param flags ao2_unlink_node_flags governing behavior.
331  *
332  * \retval 0 on errors.
333  * \retval 1 on success.
334  */
335 int __container_unlink_node_debug(struct ao2_container_node *node, uint32_t flags,
336         const char *tag, const char *file, int line, const char *func);
337
338 #define __container_unlink_node(node, flags) \
339         __container_unlink_node_debug(node, flags, NULL, NULL, 0, NULL)
340
341 void container_destruct(void *_c);
342 void container_destruct_debug(void *_c);
343 int container_init(void);
344
345 #endif /* ASTOBJ2_CONTAINER_PRIVATE_H_ */