git.sur5r.net Git - freertos/blob - Source/include/list.h

   1 /*\r
   2         FreeRTOS.org V5.1.2 - Copyright (C) 2003-2009 Richard Barry.\r
   3 \r
   4         This file is part of the FreeRTOS.org distribution.\r
   5 \r
   6         FreeRTOS.org is free software; you can redistribute it and/or modify\r
   7         it under the terms of the GNU General Public License as published by\r
   8         the Free Software Foundation; either version 2 of the License, or\r
   9         (at your option) any later version.\r
  10 \r
  11         FreeRTOS.org is distributed in the hope that it will be useful,\r
  12         but WITHOUT ANY WARRANTY; without even the implied warranty of\r
  13         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
  14         GNU General Public License for more details.\r
  15 \r
  16         You should have received a copy of the GNU General Public License\r
  17         along with FreeRTOS.org; if not, write to the Free Software\r
  18         Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA\r
  19 \r
  20         A special exception to the GPL can be applied should you wish to distribute\r
  21         a combined work that includes FreeRTOS.org, without being obliged to provide\r
  22         the source code for any proprietary components.  See the licensing section\r
  23         of http://www.FreeRTOS.org for full details of how and when the exception\r
  24         can be applied.\r
  25 \r
  26     ***************************************************************************\r
  27     ***************************************************************************\r
  28     *                                                                         *\r
  29     * Get the FreeRTOS eBook!  See http://www.FreeRTOS.org/Documentation      *\r
  30         *                                                                         *\r
  31         * This is a concise, step by step, 'hands on' guide that describes both   *\r
  32         * general multitasking concepts and FreeRTOS specifics. It presents and   *\r
  33         * explains numerous examples that are written using the FreeRTOS API.     *\r
  34         * Full source code for all the examples is provided in an accompanying    *\r
  35         * .zip file.                                                              *\r
  36     *                                                                         *\r
  37     ***************************************************************************\r
  38     ***************************************************************************\r
  39 \r
  40         Please ensure to read the configuration and relevant port sections of the\r
  41         online documentation.\r
  42 \r
  43         http://www.FreeRTOS.org - Documentation, latest information, license and \r
  44         contact details.\r
  45 \r
  46         http://www.SafeRTOS.com - A version that is certified for use in safety \r
  47         critical systems.\r
  48 \r
  49         http://www.OpenRTOS.com - Commercial support, development, porting, \r
  50         licensing and training services.\r
  51 */\r
  52 \r
  53 /*\r
  54  * This is the list implementation used by the scheduler.  While it is tailored\r
  55  * heavily for the schedulers needs, it is also available for use by\r
  56  * application code.\r
  57  *\r
  58  * xLists can only store pointers to xListItems.  Each xListItem contains a\r
  59  * numeric value (xItemValue).  Most of the time the lists are sorted in\r
  60  * descending item value order.\r
  61  *\r
  62  * Lists are created already containing one list item.  The value of this\r
  63  * item is the maximum possible that can be stored, it is therefore always at\r
  64  * the end of the list and acts as a marker.  The list member pxHead always\r
  65  * points to this marker - even though it is at the tail of the list.  This\r
  66  * is because the tail contains a wrap back pointer to the true head of\r
  67  * the list.\r
  68  *\r
  69  * In addition to it's value, each list item contains a pointer to the next\r
  70  * item in the list (pxNext), a pointer to the list it is in (pxContainer)\r
  71  * and a pointer to back to the object that contains it.  These later two\r
  72  * pointers are included for efficiency of list manipulation.  There is\r
  73  * effectively a two way link between the object containing the list item and\r
  74  * the list item itself.\r
  75  *\r
  76  *\r
  77  * \page ListIntroduction List Implementation\r
  78  * \ingroup FreeRTOSIntro\r
  79  */\r
  80 \r
  81 /*\r
  82         Changes from V4.3.1\r
  83 \r
  84         + Included local const within listGET_OWNER_OF_NEXT_ENTRY() to assist\r
  85           compiler with optimisation.  Thanks B.R.\r
  86 */\r
  87 \r
  88 #ifndef LIST_H\r
  89 #define LIST_H\r
  90 \r
  91 #ifdef __cplusplus\r
  92 extern "C" {\r
  93 #endif\r
  94 /*\r
  95  * Definition of the only type of object that a list can contain.\r
  96  */\r
  97 struct xLIST_ITEM\r
  98 {\r
  99         portTickType xItemValue;                                /*< The value being listed.  In most cases this is used to sort the list in descending order. */\r
 100         volatile struct xLIST_ITEM * pxNext;    /*< Pointer to the next xListItem in the list. */\r
 101         volatile struct xLIST_ITEM * pxPrevious;/*< Pointer to the previous xListItem in the list. */\r
 102         void * pvOwner;                                                 /*< Pointer to the object (normally a TCB) that contains the list item.  There is therefore a two way link between the object containing the list item and the list item itself. */\r
 103         void * pvContainer;                                             /*< Pointer to the list in which this list item is placed (if any). */\r
 104 };\r
 105 typedef struct xLIST_ITEM xListItem;            /* For some reason lint wants this as two separate definitions. */\r
 106 \r
 107 struct xMINI_LIST_ITEM\r
 108 {\r
 109         portTickType xItemValue;\r
 110         volatile struct xLIST_ITEM *pxNext;\r
 111         volatile struct xLIST_ITEM *pxPrevious;\r
 112 };\r
 113 typedef struct xMINI_LIST_ITEM xMiniListItem;\r
 114 \r
 115 /*\r
 116  * Definition of the type of queue used by the scheduler.\r
 117  */\r
 118 typedef struct xLIST\r
 119 {\r
 120         volatile unsigned portBASE_TYPE uxNumberOfItems;\r
 121         volatile xListItem * pxIndex;                   /*< Used to walk through the list.  Points to the last item returned by a call to pvListGetOwnerOfNextEntry (). */\r
 122         volatile xMiniListItem xListEnd;                /*< List item that contains the maximum possible item value meaning it is always at the end of the list and is therefore used as a marker. */\r
 123 } xList;\r
 124 \r
 125 /*\r
 126  * Access macro to set the owner of a list item.  The owner of a list item\r
 127  * is the object (usually a TCB) that contains the list item.\r
 128  *\r
 129  * \page listSET_LIST_ITEM_OWNER listSET_LIST_ITEM_OWNER\r
 130  * \ingroup LinkedList\r
 131  */\r
 132 #define listSET_LIST_ITEM_OWNER( pxListItem, pxOwner )          ( pxListItem )->pvOwner = ( void * ) pxOwner\r
 133 \r
 134 /*\r
 135  * Access macro to set the value of the list item.  In most cases the value is\r
 136  * used to sort the list in descending order.\r
 137  *\r
 138  * \page listSET_LIST_ITEM_VALUE listSET_LIST_ITEM_VALUE\r
 139  * \ingroup LinkedList\r
 140  */\r
 141 #define listSET_LIST_ITEM_VALUE( pxListItem, xValue )           ( pxListItem )->xItemValue = xValue\r
 142 \r
 143 /*\r
 144  * Access macro the retrieve the value of the list item.  The value can\r
 145  * represent anything - for example a the priority of a task, or the time at\r
 146  * which a task should be unblocked.\r
 147  *\r
 148  * \page listGET_LIST_ITEM_VALUE listGET_LIST_ITEM_VALUE\r
 149  * \ingroup LinkedList\r
 150  */\r
 151 #define listGET_LIST_ITEM_VALUE( pxListItem )                           ( ( pxListItem )->xItemValue )\r
 152 \r
 153 /*\r
 154  * Access macro to determine if a list contains any items.  The macro will\r
 155  * only have the value true if the list is empty.\r
 156  *\r
 157  * \page listLIST_IS_EMPTY listLIST_IS_EMPTY\r
 158  * \ingroup LinkedList\r
 159  */\r
 160 #define listLIST_IS_EMPTY( pxList )                             ( ( pxList )->uxNumberOfItems == ( unsigned portBASE_TYPE ) 0 )\r
 161 \r
 162 /*\r
 163  * Access macro to return the number of items in the list.\r
 164  */\r
 165 #define listCURRENT_LIST_LENGTH( pxList )               ( ( pxList )->uxNumberOfItems )\r
 166 \r
 167 /*\r
 168  * Access function to obtain the owner of the next entry in a list.\r
 169  *\r
 170  * The list member pxIndex is used to walk through a list.  Calling\r
 171  * listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list\r
 172  * and returns that entries pxOwner parameter.  Using multiple calls to this\r
 173  * function it is therefore possible to move through every item contained in\r
 174  * a list.\r
 175  *\r
 176  * The pxOwner parameter of a list item is a pointer to the object that owns\r
 177  * the list item.  In the scheduler this is normally a task control block.\r
 178  * The pxOwner parameter effectively creates a two way link between the list\r
 179  * item and its owner.\r
 180  *\r
 181  * @param pxList The list from which the next item owner is to be returned.\r
 182  *\r
 183  * \page listGET_OWNER_OF_NEXT_ENTRY listGET_OWNER_OF_NEXT_ENTRY\r
 184  * \ingroup LinkedList\r
 185  */\r
 186 #define listGET_OWNER_OF_NEXT_ENTRY( pxTCB, pxList )                                                                    \\r
 187 {                                                                                                                                                                               \\r
 188 xList * const pxConstList = pxList;                                                                                                             \\r
 189         /* Increment the index to the next item and return the item, ensuring */                        \\r
 190         /* we don't return the marker used at the end of the list.  */                                          \\r
 191         ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext;                                            \\r
 192         if( ( pxConstList )->pxIndex == ( xListItem * ) &( ( pxConstList )->xListEnd ) )        \\r
 193         {                                                                                                                                                                       \\r
 194                 ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext;                                    \\r
 195         }                                                                                                                                                                       \\r
 196         pxTCB = ( pxConstList )->pxIndex->pvOwner;                                                                                      \\r
 197 }\r
 198 \r
 199 \r
 200 /*\r
 201  * Access function to obtain the owner of the first entry in a list.  Lists\r
 202  * are normally sorted in ascending item value order.\r
 203  *\r
 204  * This function returns the pxOwner member of the first item in the list.\r
 205  * The pxOwner parameter of a list item is a pointer to the object that owns\r
 206  * the list item.  In the scheduler this is normally a task control block.\r
 207  * The pxOwner parameter effectively creates a two way link between the list\r
 208  * item and its owner.\r
 209  *\r
 210  * @param pxList The list from which the owner of the head item is to be\r
 211  * returned.\r
 212  *\r
 213  * \page listGET_OWNER_OF_HEAD_ENTRY listGET_OWNER_OF_HEAD_ENTRY\r
 214  * \ingroup LinkedList\r
 215  */\r
 216 #define listGET_OWNER_OF_HEAD_ENTRY( pxList )  ( ( pxList->uxNumberOfItems != ( unsigned portBASE_TYPE ) 0 ) ? ( (&( pxList->xListEnd ))->pxNext->pvOwner ) : ( NULL ) )\r
 217 \r
 218 /*\r
 219  * Check to see if a list item is within a list.  The list item maintains a\r
 220  * "container" pointer that points to the list it is in.  All this macro does\r
 221  * is check to see if the container and the list match.\r
 222  *\r
 223  * @param pxList The list we want to know if the list item is within.\r
 224  * @param pxListItem The list item we want to know if is in the list.\r
 225  * @return pdTRUE is the list item is in the list, otherwise pdFALSE.\r
 226  * pointer against\r
 227  */\r
 228 #define listIS_CONTAINED_WITHIN( pxList, pxListItem ) ( ( pxListItem )->pvContainer == ( void * ) pxList )\r
 229 \r
 230 /*\r
 231  * Must be called before a list is used!  This initialises all the members\r
 232  * of the list structure and inserts the xListEnd item into the list as a\r
 233  * marker to the back of the list.\r
 234  *\r
 235  * @param pxList Pointer to the list being initialised.\r
 236  *\r
 237  * \page vListInitialise vListInitialise\r
 238  * \ingroup LinkedList\r
 239  */\r
 240 void vListInitialise( xList *pxList );\r
 241 \r
 242 /*\r
 243  * Must be called before a list item is used.  This sets the list container to\r
 244  * null so the item does not think that it is already contained in a list.\r
 245  *\r
 246  * @param pxItem Pointer to the list item being initialised.\r
 247  *\r
 248  * \page vListInitialiseItem vListInitialiseItem\r
 249  * \ingroup LinkedList\r
 250  */\r
 251 void vListInitialiseItem( xListItem *pxItem );\r
 252 \r
 253 /*\r
 254  * Insert a list item into a list.  The item will be inserted into the list in\r
 255  * a position determined by its item value (descending item value order).\r
 256  *\r
 257  * @param pxList The list into which the item is to be inserted.\r
 258  *\r
 259  * @param pxNewListItem The item to that is to be placed in the list.\r
 260  *\r
 261  * \page vListInsert vListInsert\r
 262  * \ingroup LinkedList\r
 263  */\r
 264 void vListInsert( xList *pxList, xListItem *pxNewListItem );\r
 265 \r
 266 /*\r
 267  * Insert a list item into a list.  The item will be inserted in a position\r
 268  * such that it will be the last item within the list returned by multiple\r
 269  * calls to listGET_OWNER_OF_NEXT_ENTRY.\r
 270  *\r
 271  * The list member pvIndex is used to walk through a list.  Calling\r
 272  * listGET_OWNER_OF_NEXT_ENTRY increments pvIndex to the next item in the list.\r
 273  * Placing an item in a list using vListInsertEnd effectively places the item\r
 274  * in the list position pointed to by pvIndex.  This means that every other\r
 275  * item within the list will be returned by listGET_OWNER_OF_NEXT_ENTRY before\r
 276  * the pvIndex parameter again points to the item being inserted.\r
 277  *\r
 278  * @param pxList The list into which the item is to be inserted.\r
 279  *\r
 280  * @param pxNewListItem The list item to be inserted into the list.\r
 281  *\r
 282  * \page vListInsertEnd vListInsertEnd\r
 283  * \ingroup LinkedList\r
 284  */\r
 285 void vListInsertEnd( xList *pxList, xListItem *pxNewListItem );\r
 286 \r
 287 /*\r
 288  * Remove an item from a list.  The list item has a pointer to the list that\r
 289  * it is in, so only the list item need be passed into the function.\r
 290  *\r
 291  * @param vListRemove The item to be removed.  The item will remove itself from\r
 292  * the list pointed to by it's pxContainer parameter.\r
 293  *\r
 294  * \page vListRemove vListRemove\r
 295  * \ingroup LinkedList\r
 296  */\r
 297 void vListRemove( xListItem *pxItemToRemove );\r
 298 \r
 299 #ifdef __cplusplus\r
 300 }\r
 301 #endif\r
 302 \r
 303 #endif\r
 304 \r