Data Structures | Defines | Typedefs

core/include/list.h File Reference

Unidirectional list. More...

Data Structures

struct  os_list1_s
 structure for linking items in list More...

Defines

#define os_list1_is_empty(list1)   ( list1->next == NULL )
 condition for testing if the list is empty
#define os_list1_is_last(list1)   ( list1->next == NULL )
 condition for a test if the item is last
#define os_list1_content(list_item)   (void*)(list_item)
 conversion from list pointer to pointer of user structure
#define os_list1_item(user_item)   (os_list1_t *)( user_item )
 conversion from user structure pointer to list pointer

Typedefs

typedef struct os_list1_s os_list1_t
 data type for field that allows linking on the list

Detailed Description

Unidirectional list.

Author:
Piotr Romaniuk, (c) ELESOFTROM
Version:
1.0 Feb 4, 2011

This is implementation of unidirectional linked list. The user items that should be able to be added to the list need to have specific structure - it must have list chaining part at the beginning. It can be defined as a structural user type of the item, for example: 

 struct my_item_s{
                  os_list1_t        list_chain_field;
                  //... user content of the item 
                  //        (i.e. other fields of the item) ...
 };
Warning:
list_chain_field must be the first field in the structure.

The list code is not aware of the user contents and its structure. The structure is defined for user convenience. Only the chaining parts are used for list manipulation. Because of that, it is possible to chain items of different size and types.

The chaining part contains a reference (pointer) to next item. If the item is the last the .next field is equal to NULL.

Note:
The item can be only on one list at the time, because it can contain only one chaining part.

Each list is build starting from its head, special structure that consists of only chaining part and have no user contents. List is created and initialized by: 

 os_list1_s my_list = {NULL};

The list can be browsed and processed item by item, starting from the head and iterating through .next field until the last one is found. Consider following template: 

 os_list1_t *Litem = &list_head;
 while( !os_list1_is_last( Litem ))
 {
    struct my_item_s * m_item = os_list1_content( Litem->next );
    // process m_item 
    // if you need to remove the item from the list
        os_list1_del( prev );
        continue;//must be continue because the item was removed, otherwise one item will be missed
                  
    //if you do not remove
    prev = prev->next;              
 }

When you remove the item during list iteration, special care should be taken:
1. You must specify previous list item for deletion.
2. After the item has been deleted you should not continue traversing by .next reference but again check current item (see in above code example).

Warning:
Because of many possible scenarios of usage, provided list implementation is minimal and does not include protection from concurrent access. The user should add the guarding (e.g. critical section, mutex) that will be proper for the application and satisfy his needs.

Define Documentation

#define os_list1_content (   list_item)    (void*)(list_item)

conversion from list pointer to pointer of user structure

It should be used when conversion is required from list item to the user structure (i.e. contents).

Parameters:
[in]list_itemlist item pointer
Returns:
pointer to user structure chained on the list
Note:
It returns (void*), so conversion to user struct pointer may be needed.
#define os_list1_is_empty (   list1)    ( list1->next == NULL )

condition for testing if the list is empty

Parameters:
[in]list1pointer to list head
Returns:
value of logical test "is the list empty?"
#define os_list1_is_last (   list1)    ( list1->next == NULL )

condition for a test if the item is last

Parameters:
[in]list1pointer to tested list item
Returns:
value of test "is this element last?"
#define os_list1_item (   user_item)    (os_list1_t *)( user_item )

conversion from user structure pointer to list pointer

Use it when you need pointer of the list item and have pointer to the user structure (i.e. contents).

Parameters:
[in]user_itempointer to user structure
Returns:
pointer to list item contained in user structure