list.h 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353
  1. /*
  2. * Copyright © 2010 Intel Corporation
  3. * Copyright © 2010 Francisco Jerez <currojerez@riseup.net>
  4. *
  5. * Permission is hereby granted, free of charge, to any person obtaining a
  6. * copy of this software and associated documentation files (the "Software"),
  7. * to deal in the Software without restriction, including without limitation
  8. * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  9. * and/or sell copies of the Software, and to permit persons to whom the
  10. * Software is furnished to do so, subject to the following conditions:
  11. *
  12. * The above copyright notice and this permission notice (including the next
  13. * paragraph) shall be included in all copies or substantial portions of the
  14. * Software.
  15. *
  16. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17. * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18. * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  19. * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20. * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  21. * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  22. * IN THE SOFTWARE.
  23. *
  24. */
  25. /* Modified by Ben Skeggs <bskeggs@redhat.com> to match kernel list APIs */
  26. #ifndef _XORG_LIST_H_
  27. #define _XORG_LIST_H_
  28. /**
  29. * @file Classic doubly-link circular list implementation.
  30. * For real usage examples of the linked list, see the file test/list.c
  31. *
  32. * Example:
  33. * We need to keep a list of struct foo in the parent struct bar, i.e. what
  34. * we want is something like this.
  35. *
  36. * struct bar {
  37. * ...
  38. * struct foo *list_of_foos; -----> struct foo {}, struct foo {}, struct foo{}
  39. * ...
  40. * }
  41. *
  42. * We need one list head in bar and a list element in all list_of_foos (both are of
  43. * data type 'struct list_head').
  44. *
  45. * struct bar {
  46. * ...
  47. * struct list_head list_of_foos;
  48. * ...
  49. * }
  50. *
  51. * struct foo {
  52. * ...
  53. * struct list_head entry;
  54. * ...
  55. * }
  56. *
  57. * Now we initialize the list head:
  58. *
  59. * struct bar bar;
  60. * ...
  61. * INIT_LIST_HEAD(&bar.list_of_foos);
  62. *
  63. * Then we create the first element and add it to this list:
  64. *
  65. * struct foo *foo = malloc(...);
  66. * ....
  67. * list_add(&foo->entry, &bar.list_of_foos);
  68. *
  69. * Repeat the above for each element you want to add to the list. Deleting
  70. * works with the element itself.
  71. * list_del(&foo->entry);
  72. * free(foo);
  73. *
  74. * Note: calling list_del(&bar.list_of_foos) will set bar.list_of_foos to an empty
  75. * list again.
  76. *
  77. * Looping through the list requires a 'struct foo' as iterator and the
  78. * name of the field the subnodes use.
  79. *
  80. * struct foo *iterator;
  81. * list_for_each_entry(iterator, &bar.list_of_foos, entry) {
  82. * if (iterator->something == ...)
  83. * ...
  84. * }
  85. *
  86. * Note: You must not call list_del() on the iterator if you continue the
  87. * loop. You need to run the safe for-each loop instead:
  88. *
  89. * struct foo *iterator, *next;
  90. * list_for_each_entry_safe(iterator, next, &bar.list_of_foos, entry) {
  91. * if (...)
  92. * list_del(&iterator->entry);
  93. * }
  94. *
  95. */
  96. /**
  97. * The linkage struct for list nodes. This struct must be part of your
  98. * to-be-linked struct. struct list_head is required for both the head of the
  99. * list and for each list node.
  100. *
  101. * Position and name of the struct list_head field is irrelevant.
  102. * There are no requirements that elements of a list are of the same type.
  103. * There are no requirements for a list head, any struct list_head can be a list
  104. * head.
  105. */
  106. struct list_head {
  107. struct list_head *next, *prev;
  108. };
  109. /**
  110. * Initialize the list as an empty list.
  111. *
  112. * Example:
  113. * INIT_LIST_HEAD(&bar->list_of_foos);
  114. *
  115. * @param The list to initialized.
  116. */
  117. #define LIST_HEAD_INIT(name) { &(name), &(name) }
  118. #define LIST_HEAD(name) \
  119. struct list_head name = LIST_HEAD_INIT(name)
  120. static inline void
  121. INIT_LIST_HEAD(struct list_head *list)
  122. {
  123. list->next = list->prev = list;
  124. }
  125. static inline void
  126. __list_add(struct list_head *entry,
  127. struct list_head *prev, struct list_head *next)
  128. {
  129. next->prev = entry;
  130. entry->next = next;
  131. entry->prev = prev;
  132. prev->next = entry;
  133. }
  134. /**
  135. * Insert a new element after the given list head. The new element does not
  136. * need to be initialised as empty list.
  137. * The list changes from:
  138. * head → some element → ...
  139. * to
  140. * head → new element → older element → ...
  141. *
  142. * Example:
  143. * struct foo *newfoo = malloc(...);
  144. * list_add(&newfoo->entry, &bar->list_of_foos);
  145. *
  146. * @param entry The new element to prepend to the list.
  147. * @param head The existing list.
  148. */
  149. static inline void
  150. list_add(struct list_head *entry, struct list_head *head)
  151. {
  152. __list_add(entry, head, head->next);
  153. }
  154. /**
  155. * Append a new element to the end of the list given with this list head.
  156. *
  157. * The list changes from:
  158. * head → some element → ... → lastelement
  159. * to
  160. * head → some element → ... → lastelement → new element
  161. *
  162. * Example:
  163. * struct foo *newfoo = malloc(...);
  164. * list_add_tail(&newfoo->entry, &bar->list_of_foos);
  165. *
  166. * @param entry The new element to prepend to the list.
  167. * @param head The existing list.
  168. */
  169. static inline void
  170. list_add_tail(struct list_head *entry, struct list_head *head)
  171. {
  172. __list_add(entry, head->prev, head);
  173. }
  174. static inline void
  175. __list_del(struct list_head *prev, struct list_head *next)
  176. {
  177. next->prev = prev;
  178. prev->next = next;
  179. }
  180. /**
  181. * Remove the element from the list it is in. Using this function will reset
  182. * the pointers to/from this element so it is removed from the list. It does
  183. * NOT free the element itself or manipulate it otherwise.
  184. *
  185. * Using list_del on a pure list head (like in the example at the top of
  186. * this file) will NOT remove the first element from
  187. * the list but rather reset the list as empty list.
  188. *
  189. * Example:
  190. * list_del(&foo->entry);
  191. *
  192. * @param entry The element to remove.
  193. */
  194. static inline void
  195. list_del(struct list_head *entry)
  196. {
  197. __list_del(entry->prev, entry->next);
  198. }
  199. static inline void
  200. list_del_init(struct list_head *entry)
  201. {
  202. __list_del(entry->prev, entry->next);
  203. INIT_LIST_HEAD(entry);
  204. }
  205. static inline void list_move_tail(struct list_head *list,
  206. struct list_head *head)
  207. {
  208. __list_del(list->prev, list->next);
  209. list_add_tail(list, head);
  210. }
  211. /**
  212. * Check if the list is empty.
  213. *
  214. * Example:
  215. * list_empty(&bar->list_of_foos);
  216. *
  217. * @return True if the list contains one or more elements or False otherwise.
  218. */
  219. static inline int
  220. list_empty(struct list_head *head)
  221. {
  222. return head->next == head;
  223. }
  224. /**
  225. * Returns a pointer to the container of this list element.
  226. *
  227. * Example:
  228. * struct foo* f;
  229. * f = container_of(&foo->entry, struct foo, entry);
  230. * assert(f == foo);
  231. *
  232. * @param ptr Pointer to the struct list_head.
  233. * @param type Data type of the list element.
  234. * @param member Member name of the struct list_head field in the list element.
  235. * @return A pointer to the data struct containing the list head.
  236. */
  237. #ifndef container_of
  238. #define container_of(ptr, type, member) \
  239. (type *)((char *)(ptr) - (char *) &((type *)0)->member)
  240. #endif
  241. /**
  242. * Alias of container_of
  243. */
  244. #define list_entry(ptr, type, member) \
  245. container_of(ptr, type, member)
  246. /**
  247. * Retrieve the first list entry for the given list pointer.
  248. *
  249. * Example:
  250. * struct foo *first;
  251. * first = list_first_entry(&bar->list_of_foos, struct foo, list_of_foos);
  252. *
  253. * @param ptr The list head
  254. * @param type Data type of the list element to retrieve
  255. * @param member Member name of the struct list_head field in the list element.
  256. * @return A pointer to the first list element.
  257. */
  258. #define list_first_entry(ptr, type, member) \
  259. list_entry((ptr)->next, type, member)
  260. /**
  261. * Retrieve the last list entry for the given listpointer.
  262. *
  263. * Example:
  264. * struct foo *first;
  265. * first = list_last_entry(&bar->list_of_foos, struct foo, list_of_foos);
  266. *
  267. * @param ptr The list head
  268. * @param type Data type of the list element to retrieve
  269. * @param member Member name of the struct list_head field in the list element.
  270. * @return A pointer to the last list element.
  271. */
  272. #define list_last_entry(ptr, type, member) \
  273. list_entry((ptr)->prev, type, member)
  274. #define __container_of(ptr, sample, member) \
  275. (void *)container_of((ptr), typeof(*(sample)), member)
  276. /**
  277. * Loop through the list given by head and set pos to struct in the list.
  278. *
  279. * Example:
  280. * struct foo *iterator;
  281. * list_for_each_entry(iterator, &bar->list_of_foos, entry) {
  282. * [modify iterator]
  283. * }
  284. *
  285. * This macro is not safe for node deletion. Use list_for_each_entry_safe
  286. * instead.
  287. *
  288. * @param pos Iterator variable of the type of the list elements.
  289. * @param head List head
  290. * @param member Member name of the struct list_head in the list elements.
  291. *
  292. */
  293. #define list_for_each_entry(pos, head, member) \
  294. for (pos = __container_of((head)->next, pos, member); \
  295. &pos->member != (head); \
  296. pos = __container_of(pos->member.next, pos, member))
  297. /**
  298. * Loop through the list, keeping a backup pointer to the element. This
  299. * macro allows for the deletion of a list element while looping through the
  300. * list.
  301. *
  302. * See list_for_each_entry for more details.
  303. */
  304. #define list_for_each_entry_safe(pos, tmp, head, member) \
  305. for (pos = __container_of((head)->next, pos, member), \
  306. tmp = __container_of(pos->member.next, pos, member); \
  307. &pos->member != (head); \
  308. pos = tmp, tmp = __container_of(pos->member.next, tmp, member))
  309. #define list_for_each_entry_reverse(pos, head, member) \
  310. for (pos = __container_of((head)->prev, pos, member); \
  311. &pos->member != (head); \
  312. pos = __container_of(pos->member.prev, pos, member))
  313. #define list_for_each_entry_continue(pos, head, member) \
  314. for (pos = __container_of(pos->member.next, pos, member); \
  315. &pos->member != (head); \
  316. pos = __container_of(pos->member.next, pos, member))
  317. #define list_for_each_entry_continue_reverse(pos, head, member) \
  318. for (pos = __container_of(pos->member.prev, pos, member); \
  319. &pos->member != (head); \
  320. pos = __container_of(pos->member.prev, pos, member))
  321. #define list_for_each_entry_from(pos, head, member) \
  322. for (; \
  323. &pos->member != (head); \
  324. pos = __container_of(pos->member.next, pos, member))
  325. #endif