List Queue

group OS_87x3e_Queue

Initialize and manage List Queue functions.

List Queue is designed as a FIFO-like list, which can enqueue, dequeue and peek the list. While, List Queue also keeps these functionalities such as deleting and inserting the speicified list item.

Typedefs

typedef struct t_os_queue_elem T_OS_QUEUE_ELEM

The element structure of List Queue.

os_queue.h

Variables

void (*os_queue_init)(T_OS_QUEUE *p_queue)

Initialize the list queue.

os_queue.h

Example usage

T_OS_QUEUE  test_queue;

int test(void)
{
    // Initialize the queue before operating it.
    os_queue_init(&test_queue);
}

Param p_queue:

Pointer to the list queue header.

Return:

None.

void (*os_queue_in)(T_OS_QUEUE *p_queue, void *p_elem)

Enqueue an element to the back of the list queue.

os_queue.h

Example usage

struct test_item
{
    struct test_item *p_next; // Pointer to the next item, must be the first field.
    uint32_t          id;
    uint8_t           data[10];
}

T_OS_QUEUE  test_queue;

struct test_item a_item;

int test(void)
{
    // Initialize the queue before operating it.
    os_queue_init(&test_queue);

    // Enqueue the item.
    os_queue_in(&test_queue, &a_item);
}

Param p_queue:

Pointer to the list queue header.

Param p_elem:

The list queue element being enqueued.

Return:

None.

void *(*os_queue_out)(T_OS_QUEUE *p_queue)

Dequeue an element from the front of the list queue.

os_queue.h

Example usage

struct test_item
{
    struct test_item *p_next; // Pointer to the next item, must be the first field.
    uint32_t          id;
    uint8_t           data[10];
}

T_OS_QUEUE  test_queue;

struct test_item a_item;

int test(void)
{
    struct test_item *p_item;

    // Initialize the queue before operating it.
    os_queue_init(&test_queue);

    // Enqueue the item.
    os_queue_in(&test_queue, &a_item);

    // Then dequeue the item from the list queue.
    p_item = os_queue_out(&test_queue);
}

Param p_queue:

Pointer to the list queue header.

Return:

The first element from the list queue. If the returned address is NULL, the list queue is empty.

void *(*os_queue_peek)(T_OS_QUEUE *p_queue, int32_t index)

Peek an element from the list queue.

os_queue.h

Example usage

struct test_item
{
    struct test_item *p_next; // Pointer to the next item, must be the first field.
    uint32_t          id;
    uint8_t           data[10];
}

T_OS_QUEUE  test_queue;

struct test_item a_item;

int test(void)
{
    struct test_item *p_item;

    // Initialize the queue before operating it.
    os_queue_init(&test_queue);

    // Enqueue the item.
    os_queue_in(&test_queue, &a_item);

    // Peek but not remove the first item from the list queue.
    p_item = os_queue_peek(&test_queue, 0);
}

Param p_queue:

Pointer to the list queue header.

Param index:

The index of the peeked element. When index is a zero or positive number, it refers to the (index+1)th element. When index is a negative number, it refers to |index|th last element.

Return:

The peeked element from the list queue. If the returned address is NULL, the list queue is empty or the index is invalid.

bool (*os_queue_search)(T_OS_QUEUE *p_queue, void *p_elem)

Search an element from the list queue.

os_queue.h

Example usage

struct test_item
{
    struct test_item *p_next; // Pointer to the next item, must be the first field.
    uint32_t          id;
    uint8_t           data[10];
}

T_OS_QUEUE  test_queue;

struct test_item item1;
struct test_item item2;
struct test_item item3;

int test(void)
{
    struct test_item *p_item;

    // Initialize the queue before operating it.
    os_queue_init(&test_queue);

    // Enqueue the item 1.
    os_queue_in(&test_queue, &item1);

    // Enqueue the item 2.
    os_queue_in(&test_queue, &item2);

    // Enqueue the item 3.
    os_queue_in(&test_queue, &item3);

    // Search the item 2.
    os_queue_search(&test_queue, &item2);
}

Param p_queue:

Pointer to the list queue header.

Param p_elem:

The element to be searched.

Retval true:

Queue element was found successfully.

Retval false:

Queue element was failed to find when the queue is empty or the queue element is not in the queue.

Return:

The status of queue element searching.

void (*os_queue_insert)(T_OS_QUEUE *p_queue, void *p_elem, void *p_new_elem)

Insert an element to the list queue.

os_queue.h

Example usage

struct test_item
{
    struct test_item *p_next; // Pointer to the next item, must be the first field.
    uint32_t          id;
    uint8_t           data[10];
}

T_OS_QUEUE  test_queue;

struct test_item item1;
struct test_item item2;
struct test_item item3;

int test(void)
{
    struct test_item *p_item;

    // Initialize the queue before operating it.
    os_queue_init(&test_queue);

    // Enqueue the item 1.
    os_queue_in(&test_queue, &item1);

    // Enqueue the item 2.
    os_queue_in(&test_queue, &item2);

    // Insert the item 3 behind item 1 but before item 2.
    os_queue_insert(&test_queue, &item1, &item3);
}

Param p_queue:

Pointer to the list queue header.

Param p_elem:

The element which the new element to be inserted behind.

Param p_new_elem:

The inserted element.

Return:

None.

bool (*os_queue_delete)(T_OS_QUEUE *p_queue, void *p_elem)

Delete an element from the list queue.

os_queue.h

Example usage

struct test_item
{
    struct test_item *p_next; // Pointer to the next item, must be the first field.
    uint32_t          id;
    uint8_t           data[10];
}

T_OS_QUEUE  test_queue;

struct test_item item1;
struct test_item item2;
struct test_item item3;

int test(void)
{
    struct test_item *p_item;

    // Initialize the queue before operating it.
    os_queue_init(&test_queue);

    // Enqueue the item 1.
    os_queue_in(&test_queue, &item1);

    // Enqueue the item 2.
    os_queue_in(&test_queue, &item2);

    // Enqueue the item 3.
    os_queue_in(&test_queue, &item3);

    // Then delete the item 2.
    os_queue_delete(&test_queue, &item12);
}

Param p_queue:

Pointer to the list queue header.

Param p_elem:

The element to be deleted from the list queue.

Retval true:

Queue element was deleted successfully.

Retval false:

Queue element was failed to delete when the queue is empty or the being deleted queue element is not belonged to the queue.

Return:

The status of queue element deletion.

struct t_os_queue_elem

The element structure of List Queue.

os_queue.h

Public Members

struct t_os_queue_elem *p_next

Pointer to next list queue element.

struct T_OS_QUEUE

The header structure of List Queue.

os_queue.h

Public Members

T_OS_QUEUE_ELEM *p_first

Pointer to the first queue element.

T_OS_QUEUE_ELEM *p_last

Pointer to the last queue element.

uint16_t count

The queue element count.

uint16_t flags

The flags for customer usage.