aboutsummaryrefslogtreecommitdiffstats
path: root/include/linux/list.h
diff options
context:
space:
mode:
authorRandy Dunlap <rdunlap@xenotime.net>2006-06-25 08:47:42 -0400
committerLinus Torvalds <torvalds@g5.osdl.org>2006-06-25 13:01:06 -0400
commitfe96e57d77481c8c1b6b0381d7e086870ac394fa (patch)
treecff217baf9eeebe74b030adcc8c62cfcc01515cc /include/linux/list.h
parentdbf492d6c1a1bf5a8bda40274f479119f4c42ca4 (diff)
[PATCH] fix list.h kernel-doc
kernel-doc: Put all short function descriptions on one line or if they are too long, omit the short description & add a Description: section for them. Change some list iterator descriptions to use "current" point instead of "existing" point. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Diffstat (limited to 'include/linux/list.h')
-rw-r--r--include/linux/list.h82
1 files changed, 52 insertions, 30 deletions
diff --git a/include/linux/list.h b/include/linux/list.h
index a02642e4710a..88ecfa8f31c3 100644
--- a/include/linux/list.h
+++ b/include/linux/list.h
@@ -281,16 +281,17 @@ static inline int list_empty(const struct list_head *head)
281} 281}
282 282
283/** 283/**
284 * list_empty_careful - tests whether a list is 284 * list_empty_careful - tests whether a list is empty and not being modified
285 * empty _and_ checks that no other CPU might be 285 * @head: the list to test
286 * in the process of still modifying either member 286 *
287 * Description:
288 * tests whether a list is empty _and_ checks that no other CPU might be
289 * in the process of modifying either member (next or prev)
287 * 290 *
288 * NOTE: using list_empty_careful() without synchronization 291 * NOTE: using list_empty_careful() without synchronization
289 * can only be safe if the only activity that can happen 292 * can only be safe if the only activity that can happen
290 * to the list entry is list_del_init(). Eg. it cannot be used 293 * to the list entry is list_del_init(). Eg. it cannot be used
291 * if another CPU could re-list_add() it. 294 * if another CPU could re-list_add() it.
292 *
293 * @head: the list to test.
294 */ 295 */
295static inline int list_empty_careful(const struct list_head *head) 296static inline int list_empty_careful(const struct list_head *head)
296{ 297{
@@ -380,7 +381,7 @@ static inline void list_splice_init(struct list_head *list,
380 pos = pos->prev) 381 pos = pos->prev)
381 382
382/** 383/**
383 * list_for_each_safe - iterate over a list safe against removal of list entry 384 * list_for_each_safe - iterate over a list safe against removal of list entry
384 * @pos: the &struct list_head to use as a loop counter. 385 * @pos: the &struct list_head to use as a loop counter.
385 * @n: another &struct list_head to use as temporary storage 386 * @n: another &struct list_head to use as temporary storage
386 * @head: the head for your list. 387 * @head: the head for your list.
@@ -412,21 +413,24 @@ static inline void list_splice_init(struct list_head *list,
412 pos = list_entry(pos->member.prev, typeof(*pos), member)) 413 pos = list_entry(pos->member.prev, typeof(*pos), member))
413 414
414/** 415/**
415 * list_prepare_entry - prepare a pos entry for use as a start point in 416 * list_prepare_entry - prepare a pos entry for use in list_for_each_entry_continue
416 * list_for_each_entry_continue
417 * @pos: the type * to use as a start point 417 * @pos: the type * to use as a start point
418 * @head: the head of the list 418 * @head: the head of the list
419 * @member: the name of the list_struct within the struct. 419 * @member: the name of the list_struct within the struct.
420 *
421 * Prepares a pos entry for use as a start point in list_for_each_entry_continue.
420 */ 422 */
421#define list_prepare_entry(pos, head, member) \ 423#define list_prepare_entry(pos, head, member) \
422 ((pos) ? : list_entry(head, typeof(*pos), member)) 424 ((pos) ? : list_entry(head, typeof(*pos), member))
423 425
424/** 426/**
425 * list_for_each_entry_continue - iterate over list of given type 427 * list_for_each_entry_continue - continue iteration over list of given type
426 * continuing after existing point
427 * @pos: the type * to use as a loop counter. 428 * @pos: the type * to use as a loop counter.
428 * @head: the head for your list. 429 * @head: the head for your list.
429 * @member: the name of the list_struct within the struct. 430 * @member: the name of the list_struct within the struct.
431 *
432 * Continue to iterate over list of given type, continuing after
433 * the current position.
430 */ 434 */
431#define list_for_each_entry_continue(pos, head, member) \ 435#define list_for_each_entry_continue(pos, head, member) \
432 for (pos = list_entry(pos->member.next, typeof(*pos), member); \ 436 for (pos = list_entry(pos->member.next, typeof(*pos), member); \
@@ -434,11 +438,12 @@ static inline void list_splice_init(struct list_head *list,
434 pos = list_entry(pos->member.next, typeof(*pos), member)) 438 pos = list_entry(pos->member.next, typeof(*pos), member))
435 439
436/** 440/**
437 * list_for_each_entry_from - iterate over list of given type 441 * list_for_each_entry_from - iterate over list of given type from the current point
438 * continuing from existing point
439 * @pos: the type * to use as a loop counter. 442 * @pos: the type * to use as a loop counter.
440 * @head: the head for your list. 443 * @head: the head for your list.
441 * @member: the name of the list_struct within the struct. 444 * @member: the name of the list_struct within the struct.
445 *
446 * Iterate over list of given type, continuing from current position.
442 */ 447 */
443#define list_for_each_entry_from(pos, head, member) \ 448#define list_for_each_entry_from(pos, head, member) \
444 for (; prefetch(pos->member.next), &pos->member != (head); \ 449 for (; prefetch(pos->member.next), &pos->member != (head); \
@@ -458,12 +463,14 @@ static inline void list_splice_init(struct list_head *list,
458 pos = n, n = list_entry(n->member.next, typeof(*n), member)) 463 pos = n, n = list_entry(n->member.next, typeof(*n), member))
459 464
460/** 465/**
461 * list_for_each_entry_safe_continue - iterate over list of given type 466 * list_for_each_entry_safe_continue
462 * continuing after existing point safe against removal of list entry
463 * @pos: the type * to use as a loop counter. 467 * @pos: the type * to use as a loop counter.
464 * @n: another type * to use as temporary storage 468 * @n: another type * to use as temporary storage
465 * @head: the head for your list. 469 * @head: the head for your list.
466 * @member: the name of the list_struct within the struct. 470 * @member: the name of the list_struct within the struct.
471 *
472 * Iterate over list of given type, continuing after current point,
473 * safe against removal of list entry.
467 */ 474 */
468#define list_for_each_entry_safe_continue(pos, n, head, member) \ 475#define list_for_each_entry_safe_continue(pos, n, head, member) \
469 for (pos = list_entry(pos->member.next, typeof(*pos), member), \ 476 for (pos = list_entry(pos->member.next, typeof(*pos), member), \
@@ -472,12 +479,14 @@ static inline void list_splice_init(struct list_head *list,
472 pos = n, n = list_entry(n->member.next, typeof(*n), member)) 479 pos = n, n = list_entry(n->member.next, typeof(*n), member))
473 480
474/** 481/**
475 * list_for_each_entry_safe_from - iterate over list of given type 482 * list_for_each_entry_safe_from
476 * from existing point safe against removal of list entry
477 * @pos: the type * to use as a loop counter. 483 * @pos: the type * to use as a loop counter.
478 * @n: another type * to use as temporary storage 484 * @n: another type * to use as temporary storage
479 * @head: the head for your list. 485 * @head: the head for your list.
480 * @member: the name of the list_struct within the struct. 486 * @member: the name of the list_struct within the struct.
487 *
488 * Iterate over list of given type from current point, safe against
489 * removal of list entry.
481 */ 490 */
482#define list_for_each_entry_safe_from(pos, n, head, member) \ 491#define list_for_each_entry_safe_from(pos, n, head, member) \
483 for (n = list_entry(pos->member.next, typeof(*pos), member); \ 492 for (n = list_entry(pos->member.next, typeof(*pos), member); \
@@ -485,12 +494,14 @@ static inline void list_splice_init(struct list_head *list,
485 pos = n, n = list_entry(n->member.next, typeof(*n), member)) 494 pos = n, n = list_entry(n->member.next, typeof(*n), member))
486 495
487/** 496/**
488 * list_for_each_entry_safe_reverse - iterate backwards over list of given type safe against 497 * list_for_each_entry_safe_reverse
489 * removal of list entry
490 * @pos: the type * to use as a loop counter. 498 * @pos: the type * to use as a loop counter.
491 * @n: another type * to use as temporary storage 499 * @n: another type * to use as temporary storage
492 * @head: the head for your list. 500 * @head: the head for your list.
493 * @member: the name of the list_struct within the struct. 501 * @member: the name of the list_struct within the struct.
502 *
503 * Iterate backwards over list of given type, safe against removal
504 * of list entry.
494 */ 505 */
495#define list_for_each_entry_safe_reverse(pos, n, head, member) \ 506#define list_for_each_entry_safe_reverse(pos, n, head, member) \
496 for (pos = list_entry((head)->prev, typeof(*pos), member), \ 507 for (pos = list_entry((head)->prev, typeof(*pos), member), \
@@ -518,12 +529,13 @@ static inline void list_splice_init(struct list_head *list,
518 pos = pos->next) 529 pos = pos->next)
519 530
520/** 531/**
521 * list_for_each_safe_rcu - iterate over an rcu-protected list safe 532 * list_for_each_safe_rcu
522 * against removal of list entry
523 * @pos: the &struct list_head to use as a loop counter. 533 * @pos: the &struct list_head to use as a loop counter.
524 * @n: another &struct list_head to use as temporary storage 534 * @n: another &struct list_head to use as temporary storage
525 * @head: the head for your list. 535 * @head: the head for your list.
526 * 536 *
537 * Iterate over an rcu-protected list, safe against removal of list entry.
538 *
527 * This list-traversal primitive may safely run concurrently with 539 * This list-traversal primitive may safely run concurrently with
528 * the _rcu list-mutation primitives such as list_add_rcu() 540 * the _rcu list-mutation primitives such as list_add_rcu()
529 * as long as the traversal is guarded by rcu_read_lock(). 541 * as long as the traversal is guarded by rcu_read_lock().
@@ -551,11 +563,12 @@ static inline void list_splice_init(struct list_head *list,
551 563
552 564
553/** 565/**
554 * list_for_each_continue_rcu - iterate over an rcu-protected list 566 * list_for_each_continue_rcu
555 * continuing after existing point.
556 * @pos: the &struct list_head to use as a loop counter. 567 * @pos: the &struct list_head to use as a loop counter.
557 * @head: the head for your list. 568 * @head: the head for your list.
558 * 569 *
570 * Iterate over an rcu-protected list, continuing after current point.
571 *
559 * This list-traversal primitive may safely run concurrently with 572 * This list-traversal primitive may safely run concurrently with
560 * the _rcu list-mutation primitives such as list_add_rcu() 573 * the _rcu list-mutation primitives such as list_add_rcu()
561 * as long as the traversal is guarded by rcu_read_lock(). 574 * as long as the traversal is guarded by rcu_read_lock().
@@ -681,11 +694,14 @@ static inline void hlist_add_head(struct hlist_node *n, struct hlist_head *h)
681 694
682 695
683/** 696/**
684 * hlist_add_head_rcu - adds the specified element to the specified hlist, 697 * hlist_add_head_rcu
685 * while permitting racing traversals.
686 * @n: the element to add to the hash list. 698 * @n: the element to add to the hash list.
687 * @h: the list to add to. 699 * @h: the list to add to.
688 * 700 *
701 * Description:
702 * Adds the specified element to the specified hlist,
703 * while permitting racing traversals.
704 *
689 * The caller must take whatever precautions are necessary 705 * The caller must take whatever precautions are necessary
690 * (such as holding appropriate locks) to avoid racing 706 * (such as holding appropriate locks) to avoid racing
691 * with another list-mutation primitive, such as hlist_add_head_rcu() 707 * with another list-mutation primitive, such as hlist_add_head_rcu()
@@ -730,11 +746,14 @@ static inline void hlist_add_after(struct hlist_node *n,
730} 746}
731 747
732/** 748/**
733 * hlist_add_before_rcu - adds the specified element to the specified hlist 749 * hlist_add_before_rcu
734 * before the specified node while permitting racing traversals.
735 * @n: the new element to add to the hash list. 750 * @n: the new element to add to the hash list.
736 * @next: the existing element to add the new element before. 751 * @next: the existing element to add the new element before.
737 * 752 *
753 * Description:
754 * Adds the specified element to the specified hlist
755 * before the specified node while permitting racing traversals.
756 *
738 * The caller must take whatever precautions are necessary 757 * The caller must take whatever precautions are necessary
739 * (such as holding appropriate locks) to avoid racing 758 * (such as holding appropriate locks) to avoid racing
740 * with another list-mutation primitive, such as hlist_add_head_rcu() 759 * with another list-mutation primitive, such as hlist_add_head_rcu()
@@ -755,11 +774,14 @@ static inline void hlist_add_before_rcu(struct hlist_node *n,
755} 774}
756 775
757/** 776/**
758 * hlist_add_after_rcu - adds the specified element to the specified hlist 777 * hlist_add_after_rcu
759 * after the specified node while permitting racing traversals.
760 * @prev: the existing element to add the new element after. 778 * @prev: the existing element to add the new element after.
761 * @n: the new element to add to the hash list. 779 * @n: the new element to add to the hash list.
762 * 780 *
781 * Description:
782 * Adds the specified element to the specified hlist
783 * after the specified node while permitting racing traversals.
784 *
763 * The caller must take whatever precautions are necessary 785 * The caller must take whatever precautions are necessary
764 * (such as holding appropriate locks) to avoid racing 786 * (such as holding appropriate locks) to avoid racing
765 * with another list-mutation primitive, such as hlist_add_head_rcu() 787 * with another list-mutation primitive, such as hlist_add_head_rcu()
@@ -804,7 +826,7 @@ static inline void hlist_add_after_rcu(struct hlist_node *prev,
804 pos = pos->next) 826 pos = pos->next)
805 827
806/** 828/**
807 * hlist_for_each_entry_continue - iterate over a hlist continuing after existing point 829 * hlist_for_each_entry_continue - iterate over a hlist continuing after current point
808 * @tpos: the type * to use as a loop counter. 830 * @tpos: the type * to use as a loop counter.
809 * @pos: the &struct hlist_node to use as a loop counter. 831 * @pos: the &struct hlist_node to use as a loop counter.
810 * @member: the name of the hlist_node within the struct. 832 * @member: the name of the hlist_node within the struct.
@@ -816,7 +838,7 @@ static inline void hlist_add_after_rcu(struct hlist_node *prev,
816 pos = pos->next) 838 pos = pos->next)
817 839
818/** 840/**
819 * hlist_for_each_entry_from - iterate over a hlist continuing from existing point 841 * hlist_for_each_entry_from - iterate over a hlist continuing from current point
820 * @tpos: the type * to use as a loop counter. 842 * @tpos: the type * to use as a loop counter.
821 * @pos: the &struct hlist_node to use as a loop counter. 843 * @pos: the &struct hlist_node to use as a loop counter.
822 * @member: the name of the hlist_node within the struct. 844 * @member: the name of the hlist_node within the struct.