Lists
[User API: Pico Layer]

Defines
#define	POSLIST_ELEMENT(elem, type, member)
#define	POSLIST_IS_EMPTY(plisthead)   ((plisthead)->next == (POSLIST_t*)(plisthead))
#define	POSLIST_NEXT_ENTRY(plist)   (plist)->next
#define	POSLIST_PREV_ENTRY(plist)   (plist)->prev
#define	POSLIST_FIRST_ENTRY(plisthead)   (plisthead)->next
#define	POSLIST_LAST_ENTRY(plisthead)   (plisthead)->prev
#define	POSLIST_IS_FIRST_ENTRY(element)   ((element)->prev==(element)->head)
#define	POSLIST_IS_LAST_ENTRY(element)   ((element)->next==(element)->head)
#define	POSLIST_IS_END(plisthead, element)   ((element)==(POSLIST_t*)(plisthead))
#define	POSLIST_FOR_EACH_ENTRY(plisthead, runvar)
#define	POSLIST_FOREACH_BEGIN(plisthead, runvar, type, listmember)
#define	POSLIST_FOREACH_END
Functions
POSEXTERN void	posListAdd (POSLISTHEAD_t *listhead, UVAR_t pos, POSLIST_t *new)
POSEXTERN POSLIST_t *	posListGet (POSLISTHEAD_t *listhead, UVAR_t pos, UINT_t timeout)
POSEXTERN void	posListRemove (POSLIST_t *listelem)
POSEXTERN void	posListJoin (POSLISTHEAD_t *baselisthead, UVAR_t pos, POSLISTHEAD_t *joinlisthead)
POSEXTERN UINT_t	posListLen (POSLISTHEAD_t *listhead)
POSEXTERN void	posListInit (POSLISTHEAD_t *listhead)
POSEXTERN void	posListTerm (POSLISTHEAD_t *listhead)

---

Detailed Description

Lists are multifunctional, often they are used for buffer queues or other elements that need to be listed. pico]OS provides a set of functions for managing nonblocking and blocking lists.
Nonblocking means that elements can be put to or taken from a list without blocking the active task while an other task is also attempting to access the list. This behaviour is very usefull for interrupt service routines that need to send buffers through a queue to the application task.
An example program that demonstrates the usage of lists is available in the examples directory: lists.c

---

Define Documentation

#define POSLIST_ELEMENT (  elem, type, member   )

List Macro. This macro enables the access to the data structure that is linked with a list element. Parameters: elem  pointer to the list element of type POSLIST_t type  type of the data structure where POSLIST_t is an element from. member  the member name of the list element POSLIST_t in the structure type. Returns: a pointer to the data structure where the list element is a member from.

#define POSLIST_FIRST_ENTRY (  plisthead   )     (plisthead)->next

List Macro. Returns a pointer to the first entry of a list. Pay attention to task synchronization when using this macro.

#define POSLIST_FOR_EACH_ENTRY (  plisthead, runvar   )

List Macro. This macro expands to a for-loop that walks over all list entries in the specified list. The body of the for-loop must be enclosured in braces { }. Parameters: plisthead  pointer to the head of the list runvar  run variable of type POSLIST_t. This variable is the index variable in the for-loop. Note: When using this macro you must pay attention about task synchronization. You may need to protect all list operations by a semaphore to ensure list integrity while executing this loop. It is not allowed to take an element from the list while being in the loop. But if you plan such an operation, please see the defintion of the macros POSLIST_FOREACH_BEGIN and POSLIST_FOREACH_END.

#define POSLIST_FOREACH_BEGIN (  plisthead, runvar, type, listmember   )

List Macro. This macro expands to a complex for-loop that walks over all list entries in the specified list. This macro allows complex operations on the list while being in the loop, and it simplifies the access to the data structures that are linked to the list elements. Parameters: plisthead  pointer to the head of the list runvar  run variable of the type your data structure is. Note that this variable must be a structure pointer. This variable is the index variable in the for-loop. type  type of your data structure where POSLIST_t is an element from. listmember  the member name of the list element POSLIST_t in your data structure type. Note: When using this macro you must pay attention about task synchronization. You may need to protect all list operations by a semaphore to ensure list integrity while executing this loop. The end of the loop must be marked by the macro POSLIST_FOREACH_END. See also: POSLIST_FOREACH_END

#define POSLIST_FOREACH_END

List Macro. This macro is the counterpart to POSLIST_FOREACH_BEGIN and must be placed at the end of a for-loop that was initiated with POSLIST_FOREACH_BEGIN.

#define POSLIST_IS_EMPTY (  plisthead   )     ((plisthead)->next == (POSLIST_t*)(plisthead))

List Macro. Tests if a list is empty. Pay attention to task synchronization when using this macro.

#define POSLIST_IS_END (  plisthead, element   )     ((element)==(POSLIST_t*)(plisthead))

List Macro. Tests if the end of a list is reached when using a for-loop.

#define POSLIST_IS_FIRST_ENTRY (  element   )     ((element)->prev==(element)->head)

List Macro. Tests if an element is the first one in a list. Pay attention to task synchronization when using this macro.

#define POSLIST_IS_LAST_ENTRY (  element   )     ((element)->next==(element)->head)

List Macro. Tests if an element is the last one in a list. Pay attention to task synchronization when using this macro.

#define POSLIST_LAST_ENTRY (  plisthead   )     (plisthead)->prev

List Macro. Returns a pointer to the last element of a list. Pay attention to task synchronization when using this macro.

#define POSLIST_NEXT_ENTRY (  plist   )     (plist)->next

List Macro. Returns a pointer to the next element in a list. Pay attention to task synchronization when using this macro.

#define POSLIST_PREV_ENTRY (  plist   )     (plist)->prev

List Macro. Returns a pointer to the previous element in a list. Pay attention to task synchronization when using this macro.

---

Function Documentation

POSEXTERN void posListAdd (  POSLISTHEAD_t *  listhead, UVAR_t  pos, POSLIST_t *  new )

List Function. Adds an element to a list. Parameters: listhead  pointer to the head of the list. pos  position where to add the element. Can be POSLIST_HEAD to add the element to the head of the list or POSLIST_TAIL to add the element to the tail of the list. new  pointer to the list element to add. Note: POSCFG_FEATURE_LISTS must be defined to 1 to have list support compiled in. Note that list heads must be initialized before elements can be added to the list. See also: posListGet, posListLen, posListRemove, posListJoin, posListInit

POSEXTERN POSLIST_t* posListGet (  POSLISTHEAD_t *  listhead, UVAR_t  pos, UINT_t  timeout )

List Function. Takes an element from a list. Parameters: listhead  pointer to the head of the list. pos  position where to take the element from. Can be POSLIST_HEAD to take the element from the head of the list or POSLIST_TAIL to take the element from the tail of the list. timeout  If timeout is set to zero, the function does not wait for a new list element when the list is empty (poll mode). If timeout is set to INFINITE, the function waits infinite (without timeout) for a new list element to arrive. Any other value describes a timeout in timerticks (see HZ and MS ). If the list is still empty after the timeout ticks expired, the function returns a NULL pointer. Returns: On success, this function returns the pointer to the element and the element is removed from the list. The function returns a NULL pointer when the list is empty (timeout == 0) or the timeout has expired (timeout != 0). Note: POSCFG_FEATURE_LISTS must be defined to 1 to have list support compiled in. To be able to wait with timeout (timeout is set to nonzero and is not equal to INFINITE), the feature POSCFG_FEATURE_SEMAWAIT must be enabled. Note that only one task per time can wait for a new list element (timeout != 0). If multiple tasks attempt to wait with or without timeout for the same list, the behaviour of this function is undefined. See also: posListAdd, posListLen, posListRemove, posListJoin, posListInit

POSEXTERN void posListInit (  POSLISTHEAD_t *  listhead  )

List Function. Initializes the head of a list. This function must be called first before elements can be added to the list. Parameters: listhead  pointer to the listhead to initialize. Note: POSCFG_FEATURE_LISTS must be defined to 1 to have list support compiled in. If a list is no more used, the function posListTerm should be called to free operating system resources. See also: posListTerm, posListAdd, posListGet

POSEXTERN void posListJoin (  POSLISTHEAD_t *  baselisthead, UVAR_t  pos, POSLISTHEAD_t *  joinlisthead )

List Function. Joins two lists together. The elements contained in the joinlist are moved to the baselist. After this operation the joinlist is empty. Parameters: baselisthead  pointer to the head of the list that shall receive the elements of the second list. pos  position where the elements of the other list shall be inserted. Can be POSLIST_HEAD to insert the elements at the head of the baselist or POSLIST_TAIL to insert the elements at the tail of the baselist. joinlisthead  pointer to the list which contents shall be moved to the baselist. Note: POSCFG_FEATURE_LISTS must be defined to 1 to have list support compiled in. POSCFG_FEATURE_LISTJOIN must be defined to 1 to have this function compiled in. See also: posListAdd, posListGet, posListJoin, posListInit

POSEXTERN UINT_t posListLen (  POSLISTHEAD_t *  listhead  )

List Function. Returns the length of a list. Parameters: listhead  pointer to the head of the list. Returns: the length of the list Note: POSCFG_FEATURE_LISTS must be defined to 1 to have list support compiled in. POSCFG_FEATURE_LISTLEN must be defined to 1 to have this function compiled in. See also: posListAdd, posListGet, posListRemove

POSEXTERN void posListRemove (  POSLIST_t *  listelem  )

List Function. Removes an element from a list. Parameters: listelem  pointer to the element to remove. Note: POSCFG_FEATURE_LISTS must be defined to 1 to have list support compiled in. See also: posListAdd, posListGet, posListLen, posListJoin, posListInit

POSEXTERN void posListTerm (  POSLISTHEAD_t *  listhead  )

List Function. Frees operating system resources when a list is no more needed. Parameters: listhead  pointer to the head of the list. Note: POSCFG_FEATURE_LISTS must be defined to 1 to have list support compiled in.

---