【FreeRTOS】学习笔记（十）

列表相关API函数介绍

函数	描述
vLIstInitialise()	初始化列表
vListInitialiseItem()	初始化列表项
vListInsertEnd()	列表末尾插入列表项
vListInsert()	列表插入列表项
uxListRemove()	列表移除列表项

---

初始化列表vListInitialise()

void vListInitialise( List_t * const pxList )
{
    /* 初始化时，列表中只有xListEnd，因此pxIndex指向xListEnd */
    pxList->pxIndex = ( ListItem_t * ) &( pxList->xListEnd ); /*lint !e826 !e740 !e9087 The mini list structure is used as the list end to save RAM.  This is checked and valid. */

    /* xListEnd的值初始化为最大值，用于列表项升序排序时，排在最后 */
    pxList->xListEnd.xItemValue = portMAX_DELAY;

    /* 初始化时，列表中只有xListEnd，因此上一个和下一个列表项都为xListEnd本身 */
    pxList->xListEnd.pxNext = ( ListItem_t * ) &( pxList->xListEnd ); 
    pxList->xListEnd.pxPrevious = ( ListItem_t * ) &( pxList->xListEnd ); 
    
    /* 初始化时，列表中的列表项数量为0（不包含xListEnd） */
    pxList->uxNumberOfItems = ( UBaseType_t ) 0U;

    /* 初始化时用于检测列表数据完整性的校验值 */
    listSET_LIST_INTEGRITY_CHECK_1_VALUE( pxList );
    listSET_LIST_INTEGRITY_CHECK_2_VALUE( pxList );
}

---

函数vListInitialiseItem()

void vListInitialiseItem( ListItem_t * const pxItem )
{
    /* 初始化时，列表项所在列表设为空 */
    pxItem->pxContainer = NULL;

    /* 初始化用于检测列表项数据完整性的校验值 */
    listSET_FIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE( pxItem );
    listSET_SECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE( pxItem );
}

---

函数vListInsert()

此函数用于将待插入列表的列表项按照列表项值升序进行排序，有序地插入到列表中。

void vListInsert( List_t * const pxList,
                  ListItem_t * const pxNewListItem )
{
    ListItem_t * pxIterator;
    /* 获取列表项的数值依据数值升序排列 */
    const TickType_t xValueOfInsertion = pxNewListItem->xItemValue;

    /* 检查参数是否正确 */
    listTEST_LIST_INTEGRITY( pxList );
    listTEST_LIST_ITEM_INTEGRITY( pxNewListItem );

    /* 插入位置为列表xListEnd前面 */
    if( xValueOfInsertion == portMAX_DELAY )
    {
        pxIterator = pxList->xListEnd.pxPrevious;
    }
    else
    {
        /* 遍历列表找到插入的合适位置 */
        for( pxIterator = ( ListItem_t * ) &( pxList->xListEnd ); pxIterator->pxNext->xItemValue <= xValueOfInsertion; pxIterator = pxIterator->pxNext ) 
        {
            /* There is nothing to do here, just iterating to the wanted
             * insertion position. */
        }
    }
	/* 双向列表的插入操作 */
    pxNewListItem->pxNext = pxIterator->pxNext;
    pxNewListItem->pxNext->pxPrevious = pxNewListItem;
    pxNewListItem->pxPrevious = pxIterator;
    pxIterator->pxNext = pxNewListItem;

    /* 更新列表项所属列表 */
    pxNewListItem->pxContainer = pxList;

    ( pxList->uxNumberOfItems )++;
}

---

函数vListInsertEnd()

此函数用于将待插入列表的列表项插入到列表pxIndex指针指向的列表项的前面，是一种无序的插入方式

void vListInsertEnd( List_t * const pxList,
                     ListItem_t * const pxNewListItem )
{
	/* 获取列表pxIndex指向的列表项 */
    ListItem_t * const pxIndex = pxList->pxIndex;

    /* Only effective when configASSERT() is also defined, these tests may catch
     * the list data structures being overwritten in memory.  They will not catch
     * data errors caused by incorrect configuration or use of FreeRTOS. */
    listTEST_LIST_INTEGRITY( pxList );
    listTEST_LIST_ITEM_INTEGRITY( pxNewListItem );

    /* 更新待插入列表项的指针成员变量 */
    pxNewListItem->pxNext = pxIndex;
    pxNewListItem->pxPrevious = pxIndex->pxPrevious;

    /* Only used during decision coverage testing. */
    mtCOVERAGE_TEST_DELAY();

	/* 更新列表中原本列表项的指针成员变量 */
    pxIndex->pxPrevious->pxNext = pxNewListItem;
    pxIndex->pxPrevious = pxNewListItem;

    /* 更新待插入列表项的所在列表成员变量 */
    pxNewListItem->pxContainer = pxList;

	/* 更新列表中列表项的数量 */
    ( pxList->uxNumberOfItems )++;
}

---

函数uxListRemove()

此函数用于将列表项从列表项所在的列表中移除

UBaseType_t uxListRemove( ListItem_t * const pxItemToRemove )
{
/* The list item knows which list it is in.  Obtain the list from the list
 * item. */
    List_t * const pxList = pxItemToRemove->pxContainer;
	/* 从列表中移除列表项 */
    pxItemToRemove->pxNext->pxPrevious = pxItemToRemove->pxPrevious;
    pxItemToRemove->pxPrevious->pxNext = pxItemToRemove->pxNext;

    /* Only used during decision coverage testing. */
    mtCOVERAGE_TEST_DELAY();

    /* 如果pxIndex正指向待移除的列表项 */
    if( pxList->pxIndex == pxItemToRemove )
    {
    	/* pxIndex指向上一个列表项 */
        pxList->pxIndex = pxItemToRemove->pxPrevious;
    }
    else
    {
        mtCOVERAGE_TEST_MARKER();
    }
	/* 将待移除的列表项的所在列表指针清空 */
    pxItemToRemove->pxContainer = NULL;
    /* 更新列表中列表项的数量 */
    ( pxList->uxNumberOfItems )--;

    return pxList->uxNumberOfItems;
}