VirtualBox

Changeset 26740 in vbox for trunk/include/iprt


Ignore:
Timestamp:
Feb 24, 2010 12:49:33 PM (15 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
57990
Message:

iprt/list.h: r=bird: Mostly docs, but added a drop of poison to RTListNodeRemove and added parenthesis around some macro arguments.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/iprt/list.h

    r26739 r26740  
    11/** @file
    2  * IPRT - List handling functions.
     2 * IPRT - Generic Doubly Linked List.
    33 */
    44
    55/*
    6  * Copyright (C) 2006-2007 Sun Microsystems, Inc.
     6 * Copyright (C) 2010 Sun Microsystems, Inc.
    77 *
    88 * This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    3232
    3333#include <iprt/types.h>
    34 #include <iprt/cdefs.h>
    35 
    36 /** @defgroup grp_rt_list    RTList - Generic List Interface.
     34
     35/** @defgroup grp_rt_list    RTList - Generic Doubly Linked List
    3736 * @ingroup grp_rt
     37 *
     38 * The list implementation is circular without any type wise distintion between
     39 * the list and its nodes.  This can be confusing since the list head usually
     40 * resides in a different structure than the nodes, so care must be taken when
     41 * walking the list.
     42 *
    3843 * @{
    3944 */
    … …  
    4247
    4348/**
    44  * A list node of a double linked list.
     49 * A list node of a doubly linked list.
    4550 */
    4651typedef struct RTLISTNODE
    … …  
    5964 * Initialize a list.
    6065 *
    61  * @returns nothing.
    62  * @param   pList    Pointer to an unitialised list.
     66 * @param   pList               Pointer to an unitialised list.
    6367 */
    6468DECLINLINE(void) RTListInit(PRTLISTNODE pList)
    … …  
    6973
    7074/**
    71  * Append a node to the end of the list
    72  *
    73  * @returns nothing.
    74  * @param   pList    The list to append the node to.
    75  * @param   pNode    The node to append.
     75 * Append a node to the end of the list.
     76 *
     77 * @param   pList               The list to append the node to.
     78 * @param   pNode               The node to append.
    7679 */
    7780DECLINLINE(void) RTListAppend(PRTLISTNODE pList, PRTLISTNODE pNode)
    … …  
    8487
    8588/**
    86  * Add a node as the first element of the list
    87  *
    88  * @returns nothing.
    89  * @param   pList    The list to prepend the node to.
    90  * @param   pNode    The node to prepend.
     89 * Add a node as the first element of the list.
     90 *
     91 * @param   pList               The list to prepend the node to.
     92 * @param   pNode               The node to prepend.
    9193 */
    9294DECLINLINE(void) RTListPrepend(PRTLISTNODE pList, PRTLISTNODE pNode)
    … …  
    101103 * Remove a node from a list.
    102104 *
    103  * @returns nothing.
    104  * @param   pNode    The node to remove.
     105 * @param   pNode               The node to remove.
    105106 */
    106107DECLINLINE(void) RTListNodeRemove(PRTLISTNODE pNode)
    … …  
    111112    pPrev->pNext = pNext;
    112113    pNext->pPrev = pPrev;
    113 }
    114 
    115 /**
    116  * Checks if a node is the last element in the list
    117  *
    118  * @returns true if the node is the last element in the list.
    119  *          false otherwise
    120  * @param   list    The list.
    121  * @param   node    The node to check.
    122  */
    123 #define RTListNodeIsLast(list, node) ((node)->pNext == list)
    124 
    125 /**
    126  * Checks if a node is the first element in the list
    127  *
    128  * @returns true if the node is the first element in the list.
    129  *          false otherwise
    130  * @param   list    The list.
    131  * @param   node    The node to check.
    132  */
    133 #define RTListNodeIsFirst(list, node) ((node)->pPrev == list)
     114
     115    /* poison */
     116    pNode->pNext = NULL;
     117    pNode->pPrev = NULL;
     118}
     119
     120/**
     121 * Checks if a node is the last element in the list.
     122 *
     123 * @retval  @c true if the node is the last element in the list.
     124 * @retval  @c false otherwise
     125 *
     126 * @param   pList               The list.
     127 * @param   pNode               The node to check.
     128 */
     129#define RTListNodeIsLast(pList, pNode)  ((pNode)->pNext == (pList))
     130
     131/**
     132 * Checks if a node is the first element in the list.
     133 *
     134 * @retval  @c true if the node is the first element in the list.
     135 * @retval  @c false otherwise.
     136 *
     137 * @param   pList               The list.
     138 * @param   pNode               The node to check.
     139 */
     140#define RTListNodeIsFirst(pList, pNode) ((pNode)->pPrev == (pList))
    134141
    135142/**
    136143 * Checks if a list is empty.
    137144 *
    138  * @returns true if the list is empty
    139  *          false otherwise
    140  * @param   list    The list to check.
    141  */
    142 #define RTListIsEmpty(list) ((list)->pPrev == list)
     145 * @retval  @c true if the list is empty.
     146 * @retval  @c false otherwise.
     147 *
     148 * @param   pList               The list to check.
     149 */
     150#define RTListIsEmpty(pList)            ((pList)->pPrev == (pList))
    143151
    144152/**
    145153 * Returns the next node in the list.
    146154 *
    147  * @returns Next node.
    148  * @param   node   The current node.
    149  * @param   type   Structure the list node is a member of.
    150  * @param   member The list node member.
    151  */
    152 #define RTListNodeGetNext(node, type, member) ((type *)((uint8_t *)((node)->pNext) - RT_OFFSETOF(type, member)))
     155 * @returns The next node.
     156 *
     157 * @param   pCurNode            The current node.
     158 * @param   Type                Structure the list node is a member of.
     159 * @param   Member              The list node member.
     160 */
     161#define RTListNodeGetNext(pCurNode, Type, Member) \
     162    RT_FROM_MEMBER((pCurNode)->pNext, Type, Member)
    153163
    154164/**
    155165 * Returns the previous node in the list.
    156166 *
    157  * @returns Next node.
    158  * @param   node   The current node.
    159  * @param   type   Structure the list node is a member of.
    160  * @param   member The list node member.
    161  */
    162 #define RTListNodeGetPrev(node, type, member) ((type *)((uint8_t *)((node)->pPrev) - RT_OFFSETOF(type, member)))
    163 
    164 /**
    165  * Returns the first element in the list
    166  * or NULL if the list is empty.
    167  *
    168  * @returns Pointer to the first list element
    169  *          or NULL if the list is empty.
    170  * @param   list    List to get the first element from.
    171  * @param   type   Structure the list node is a member of.
    172  * @param   member The list node member.
    173  */
    174 #define RTListNodeGetFirst(list, type, member) (RTListIsEmpty(list) ? NULL : RTListNodeGetNext(list, type, member))
    175 
    176 /**
    177  * Returns the last element in the list
    178  * or NULL if the list is empty.
    179  *
    180  * @returns Pointer to the last list element
    181  *          or NULL if the list is empty.
    182  * @param   list    List to get the first element from.
    183  * @param   type   Structure the list node is a member of.
    184  * @param   member The list node member.
    185  */
    186 #define RTListNodeGetLast(list, type, member) (RTListIsEmpty(list) ? NULL : RTListNodeGetPrev(list, type, member))
     167 * @returns The previous node.
     168 *
     169 * @param   pCurNode            The current node.
     170 * @param   Type                Structure the list node is a member of.
     171 * @param   Member              The list node member.
     172 */
     173#define RTListNodeGetPrev(pCurNode, Type, Member) \
     174    RT_FROM_MEMBER((pCurNode)->pPrev, Type, Member)
     175
     176/**
     177 * Returns the first element in the list (checks for empty list).
     178 *
     179 * @retval  Pointer to the first list element.
     180 * @retval  NULL if the list is empty.
     181 *
     182 * @param   pList               List to get the first element from.
     183 * @param   Type                Structure the list node is a member of.
     184 * @param   Member              The list node member.
     185 */
     186#define RTListNodeGetFirst(pList, Type, Member) \
     187    (!RTListIsEmpty(pList) ? RTListNodeGetNext(pList, Type, Member) : NULL)
     188
     189/**
     190 * Returns the last element in the list (checks for empty list).
     191 *
     192 * @retval  Pointer to the last list element.
     193 * @retval  NULL if the list is empty.
     194 *
     195 * @param   pList               List to get the last element from.
     196 * @param   Type                Structure the list node is a member of.
     197 * @param   Member              The list node member.
     198 */
     199#define RTListNodeGetLast(pList, Type, Member) \
     200    (!RTListIsEmpty(pList) ? RTListNodeGetPrev(pList, Type, Member) : NULL)
    187201
    188202RT_C_DECLS_END
Note: See TracChangeset for help on using the changeset viewer.

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette