wl_list(3) Wayland wl_list(3)
NAME
wl_list - Doubly-linked list.
SYNOPSIS
#include <wayland-util.h>
Public Member Functions
void wl_list_init (struct wl_list *list)
void wl_list_insert (struct wl_list *list, struct wl_list *elm)
void wl_list_remove (struct wl_list *elm)
int wl_list_length (const struct wl_list *list)
int wl_list_empty (const struct wl_list *list)
void wl_list_insert_list (struct wl_list *list, struct wl_list *other)
Data Fields
struct wl_list * prev
struct wl_list * next
Related Functions
(Note that these are not member functions.)
#define wl_list_for_each(pos, head, member)
#define wl_list_for_each_safe(pos, tmp, head, member)
#define wl_list_for_each_reverse(pos, head, member)
#define wl_list_for_each_reverse_safe(pos, tmp, head, member)
Detailed Description
Doubly-linked list.
On its own, an instance of struct wl_list represents the sentinel head
of a doubly-linked list, and must be initialized using wl_list_init().
When empty, the list head's next and prev members point to the list
head itself, otherwise next references the first element in the list,
and prev refers to the last element in the list.
Use the struct wl_list type to represent both the list head and the
links between elements within the list. Use wl_list_empty() to
determine if the list is empty in O(1).
All elements in the list must be of the same type. The element type
must have a struct wl_list member, often named link by convention.
Prior to insertion, there is no need to initialize an element's link -
invoking wl_list_init() on an individual list element's struct wl_list
member is unnecessary if the very next operation is wl_list_insert().
However, a common idiom is to initialize an element's link prior to
removal - ensure safety by invoking wl_list_init() before
wl_list_remove().
Consider a list reference struct wl_list foo_list, an element type as
struct element, and an element's link member as struct wl_list link.
The following code initializes a list and adds three elements to it.
struct wl_list foo_list;
struct element {
int foo;
struct wl_list link;
};
struct element e1, e2, e3;
wl_list_init(&foo_list);
wl_list_insert(&foo_list, &e1.link); // e1 is the first element
wl_list_insert(&foo_list, &e2.link); // e2 is now the first element
wl_list_insert(&e2.link, &e3.link); // insert e3 after e2
The list now looks like [e2, e3, e1].
The wl_list API provides some iterator macros. For example, to iterate
a list in ascending order:
struct element *e;
wl_list_for_each(e, foo_list, link) {
do_something_with_element(e);
}
See the documentation of each iterator for details.
See also
http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/linux/list.h
Member Function Documentation
int wl_list_empty (const struct wl_list * list)
Determines if the list is empty.
Parameters
list List whose emptiness is to be determined
Returns
1 if empty, or 0 if not empty
void wl_list_init (struct wl_list * list)
Initializes the list.
Parameters
list List to initialize
void wl_list_insert (struct wl_list * list, struct wl_list * elm)
Inserts an element into the list, after the element represented by
list. When list is a reference to the list itself (the head), set the
containing struct of elm as the first element in the list.
Note
If elm is already part of a list, inserting it again will lead to
list corruption.
Parameters
list List element after which the new element is inserted
elm Link of the containing struct to insert into the list
void wl_list_insert_list (struct wl_list * list, struct wl_list * other)
Inserts all of the elements of one list into another, after the element
represented by list.
Note
This leaves other in an invalid state.
Parameters
list List element after which the other list elements will be
inserted
other List of elements to insert
int wl_list_length (const struct wl_list * list)
Determines the length of the list.
Note
This is an O(n) operation.
Parameters
list List whose length is to be determined
Returns
Number of elements in the list
void wl_list_remove (struct wl_list * elm)
Removes an element from the list.
Note
This operation leaves elm in an invalid state.
Parameters
elm Link of the containing struct to remove from the list
Friends And Related Function Documentation
#define wl_list_for_each(pos, head, member) [related]
Value:
for (pos = wl_container_of((head)->next, pos, member); &pos->member != (head); pos = wl_container_of(pos->member.next, pos, member))
Iterates over a list.
This macro expresses a for-each iterator for wl_list. Given a list and
wl_list link member name (often named link by convention), this macro
assigns each element in the list to pos, which can then be referenced
in a trailing code block. For example, given a wl_list of struct
message elements:
struct message {
char *contents;
wl_list link;
};
struct wl_list *message_list;
// Assume message_list now "contains" many messages
struct message *m;
wl_list_for_each(m, message_list, link) {
do_something_with_message(m);
}
Parameters
pos Cursor that each list element will be assigned to
head Head of the list to iterate over
member Name of the link member within the element struct
#define wl_list_for_each_reverse(pos, head, member) [related]
Value:
for (pos = wl_container_of((head)->prev, pos, member); &pos->member != (head); pos = wl_container_of(pos->member.prev, pos, member))
Iterates backwards over a list.
See also
wl_list_for_each()
Parameters
pos Cursor that each list element will be assigned to
head Head of the list to iterate over
member Name of the link member within the element struct
#define wl_list_for_each_reverse_safe(pos, tmp, head, member) [related]
Value:
for (pos = wl_container_of((head)->prev, pos, member), tmp = wl_container_of((pos)->member.prev, tmp, member); &pos->member != (head); pos = tmp, tmp = wl_container_of(pos->member.prev, tmp, member))
Iterates backwards over a list, safe against removal of the list
element.
Note
Only removal of the current element, pos, is safe. Removing any
other element during traversal may lead to a loop malfunction.
See also
wl_list_for_each()
Parameters
pos Cursor that each list element will be assigned to
tmp Temporary pointer of the same type as pos
head Head of the list to iterate over
member Name of the link member within the element struct
#define wl_list_for_each_safe(pos, tmp, head, member) [related]
Value:
for (pos = wl_container_of((head)->next, pos, member), tmp = wl_container_of((pos)->member.next, tmp, member); &pos->member != (head); pos = tmp, tmp = wl_container_of(pos->member.next, tmp, member))
Iterates over a list, safe against removal of the list element.
Note
Only removal of the current element, pos, is safe. Removing any
other element during traversal may lead to a loop malfunction.
See also
wl_list_for_each()
Parameters
pos Cursor that each list element will be assigned to
tmp Temporary pointer of the same type as pos
head Head of the list to iterate over
member Name of the link member within the element struct
Field Documentation
struct wl_list* wl_list::next
Next list element
struct wl_list* wl_list::prev
Previous list element
Author
Generated automatically by Doxygen for Wayland from the source code.
Version 1.20.0 Wed Sep 14 2022 wl_list(3)
Generated by dwww version 1.14 on Mon Feb 3 07:44:14 CET 2025.