Doubly Linked List

Basic Concepts

A doubly linked list is a linked data structure that consists of a set of sequentially linked records called nodes. Each node contains a pointer to the previous node and a pointer to the next node in the sequence of nodes. The pointer head is unique. A doubly linked list allows access from a list node to its next node and also the previous node on the list. This data structure facilitates data search, especially traversal of a large amount of data. The symmetry of the doubly linked list also makes operations, such as insertion and deletion, easy. However, pay attention to the pointer direction when performing operations.

Available APIs

The following table describes APIs available for the doubly linked list. For more details about the APIs, see the API reference.

Category

API

Description

Initializing a linked list

LOS_ListInit

Initializes a specified node as a doubly linked list node.

LOS_DL_LIST_HEAD

Defines a node and initializes it as a doubly linked list node.

Adding a node

LOS_ListAdd

Inserts the specified node to the head of a doubly linked list.

LOS_ListHeadInsert

Inserts the specified node to the head of a doubly linked list. It is the same as LOS_ListAdd.

LOS_ListTailInsert

Inserts the specified node to the end of a doubly linked list.

Adding a linked list

LOS_ListAddList

Inserts the head of a specified linked list into the head of a doubly linked list.

LOS_ListHeadInsertList

Inserts the head of a specified linked list into the head of a doubly linked list. It is the same as LOS_ListAddList.

LOS_ListTailInsertList

Inserts the end of a specified linked list into the head of a doubly linked list.

Deleting a node

LOS_ListDelete

Deletes the specified node from a doubly linked list.

LOS_ListDelInit

Deletes the specified node from the linked list and uses the node to initialize the linked list.

Determining a doubly linked list

LOS_ListEmpty

Checks whether a linked list is empty.

LOS_DL_LIST_IS_END

Checks whether the specified linked list node is at the end of the linked list.

LOS_DL_LIST_IS_ON_QUEUE

Check whether the linked list node is in a doubly linked list.

Obtaining structure information

LOS_OFF_SET_OF

Obtains the offset of a member in a specified structure relative to the start address of the structure.

LOS_DL_LIST_ENTRY

Obtains the address of the structure that contains the first node in the linked list. The first input parameter of the API indicates the head node in the list, the second input parameter indicates the name of the structure to be obtained, and the third input parameter indicates the name of the linked list in the structure.

LOS_ListPeekHeadType

Obtains the address of the structure that contains the first node in the linked list. The first input parameter of the API indicates the head node in the list, the second input parameter indicates the name of the structure to be obtained, and the third input parameter indicates the name of the linked list in the structure. Return Null if the linked list is empty.

LOS_ListRemoveHeadType

Obtains the address of the structure that contains the first node in the linked list, and deletes the first node from the list. The first input parameter of the API indicates the head node in the list, the second input parameter indicates the name of the structure to be obtained, and the third input parameter indicates the name of the linked list in the structure. Return Null if the linked list is empty.

LOS_ListNextType

Obtains the address of the structure that contains the next node of the specified node in the linked list. The first input parameter of the API indicates the head node in the list, the second input parameter indicates the specified node, the third parameter indicates the name of the structure to be obtained, and the fourth input parameter indicates the name of the linked list in the structure. If the next node of the linked list node is the head node and is empty, NULL is returned.

Traversing a doubly linked list

LOS_DL_LIST_FOR_EACH

Traverses a doubly linked list.

LOS_DL_LIST_FOR_EACH_SAFE

Traverses a doubly linked list, and stores the next node of the current node for security verification.

Traversing the structure that contains the doubly linked list

LOS_DL_LIST_FOR_EACH_ENTRY

Traverses the specified doubly linked list and obtains the address of the structure that contains the linked list node.

LOS_DL_LIST_FOR_EACH_ENTRY_SAFE

Traverses the specified doubly linked list, obtains the structure address of the node that contains the linked list, and stores the structure address that contains the next node of the current node.

How to Develop

The typical development process of the doubly linked list is as follows:

  1. Call LOS_ListInit/LOS_DL_LIST_HEAD to initialize a doubly linked list.
  2. Call LOS_ListAdd to insert a node to the list.
  3. Call LOS_ListTailInsert to insert a node to the end of the list.
  4. Call LOS_ListDelete to delete the specified node.
  5. Call LOS_ListEmpty to check whether a linked list is empty.
  6. Call LOS_ListDelInit to delete a specified node, and initialize the linked list based on this node.

NOTE:

  • Pay attention to the operations of the front and back pointer of the node.
  • The linked list operation APIs are underlying APIs and do not check whether the input parameters are empty. You must ensure that the input parameters are valid.
  • If the memory of a linked list node is dynamically requested, release the memory after deleting the node.

Development Example

Example Description

This example implements the following:

  1. Initialize a doubly linked list.
  2. Add nodes.
  3. Delete a node.
  4. Check whether the operation is performed successfully.
#include "stdio.h"
#include "los_list.h"

static UINT32 ListSample(VOID)
{
    LOS_DL_LIST listHead = {NULL,NULL};
    LOS_DL_LIST listNode1 = {NULL,NULL};
    LOS_DL_LIST listNode2 = {NULL,NULL};

    // Initialize the linked list.
    PRINTK("Initial head\n");
    LOS_ListInit(&listHead);

    // Add node 1 and node 2 and verify their relationship.
    LOS_ListAdd(&listHead, &listNode1);
    if (listNode1.pstNext == &listHead && listNode1.pstPrev == &listHead) {
        PRINTK("Add listNode1 success\n");
    }

    LOS_ListTailInsert(&listHead, &listNode2);
    if (listNode2.pstNext == &listHead && listNode2.pstPrev == &listNode1) {
        PRINTK("Tail insert listNode2 success\n");
    }

    // Delete the two nodes.
    LOS_ListDelete(&listNode1);
    LOS_ListDelete(&listNode2);

    // Check that the linked list is empty.
    if (LOS_ListEmpty(&listHead)) {
        PRINTK("Delete success\n");
    }

    return LOS_OK;
}

Verification

The development is successful if the return result is as follows:

Initial head 
Add listNode1 success 
Tail insert listNode2 success
Delete success