xserver/include/list.h

32  * @file Classic doubly-link circular list implementation.
33  * For real usage examples of the linked list, see the file test/list.c
36  * We need to keep a list of struct foo in the parent struct bar, i.e. what
45  * We need one list head in bar and a list element in all list_of_foos (both are of
60  * Now we initialize the list head:
66  * Then we create the first element and add it to this list:
72  * Repeat the above for each element you want to add to the list. Deleting
78  * list again.
80  * Looping through the list requires a 'struct foo' as iterator and the
101  * The linkage struct for list nodes. This struct must be part of your
103  * list and for each list node.
106  * There are no requirements that elements of a list are of the same type.
107  * There are no requirements for a list head, any struct xorg_list can be a list
115  * Initialize the list as an empty list.
120  * @param list The list to initialize
123 xorg_list_init(struct xorg_list *list)  in xorg_list_init()  argument
125     list->next = list->prev = list;  in xorg_list_init()
139  * Insert a new element after the given list head. The new element does not
140  * need to be initialised as empty list.
141  * The list changes from:
150  * @param entry The new element to prepend to the list.
151  * @param head The existing list.
160  * Append a new element to the end of the list given with this list head.
162  * The list changes from:
171  * @param entry The new element to prepend to the list.
172  * @param head The existing list.
188  * Remove the element from the list it is in. Using this function will reset
189  * the pointers to/from this element so it is removed from the list. It does
192  * Using xorg_list_del on a pure list head (like in the example at the top of
194  * the list but rather reset the list as empty list.
209  * Check if the list is empty.
214  * @return True if the list is empty or False if the list contains one or more
224  * Returns a pointer to the container of this list element.
232  * @param type Data type of the list element.
233  * @param member Member name of the struct xorg_list field in the list element.
234  * @return A pointer to the data struct containing the list head.
248  * Retrieve the first list entry for the given list pointer.
254  * @param ptr The list head
255  * @param type Data type of the list element to retrieve
256  * @param member Member name of the struct xorg_list field in the list element.
257  * @return A pointer to the first list element.
263  * Retrieve the last list entry for the given listpointer.
269  * @param ptr The list head
270  * @param type Data type of the list element to retrieve
271  * @param member Member name of the struct xorg_list field in the list element.
272  * @return A pointer to the last list element.
292  * Loop through the list given by head and set pos to struct in the list.
303  * @param pos Iterator variable of the type of the list elements.
304  * @param head List head
305  * @param member Member name of the struct xorg_list in the list elements.
315  * Loop through the list, keeping a backup pointer to the element. This
316  * macro allows for the deletion of a list element while looping through the
317  * list.
328 /* NULL-Terminated List Interface
345  * Init the element as null-terminated list.
348  * struct foo *list = malloc();
349  * nt_list_init(list, next);
351  * @param list The list element that will be the start of the list
358  * Returns the next element in the list or NULL on termination.
361  * struct foo *element = list;
367  * @param list The list or current element.
374  * Iterate through each element in the list.
378  * nt_list_for_each_entry(iterator, list, next) {
382  * @param entry Assigned to the current list element
383  * @param list The list to iterate through.
390  * Iterate through each element in the list, keeping a backup pointer to the
391  * element. This macro allows for the deletion of a list element while
392  * looping through the list.
396  * @param entry Assigned to the current list element
398  * @param list The list to iterate through.
407  * Append the element to the end of the list. This macro may be used to
413  * nt_list_append(elem, list, struct foo, next);
415  * Resulting list order:
418  * @param entry An entry (or list) to append to the list
419  * @param list The list to append to. This list must be a valid list, not
421  * @param type The list type
432  * Insert the element at the next position in the list. This macro may be
433  * used to insert a list into a list.
437  * nt_list_insert(elem, list, struct foo, next);
439  * Resulting list order:
442  * @param entry An entry (or list) to append to the list
443  * @param list The list to insert to. This list must be a valid list, not
445  * @param type The list type
455  * Delete the entry from the list by iterating through the list and
456  * removing any reference from the list to the entry.
460  * nt_list_del(elem, list, struct foo, next);
462  * @param entry The entry to delete from the list. entry is always
463  * re-initialized as a null-terminated list.
464  * @param list The list containing the entry, set to the new list without
466  * @param type The list type
488  * list functions. Unfortunately, the xf86OptionRec uses it and we can't