simplelist.h File Reference

---

Detailed Description

Simple read-only, lockable, append-only list implementation.

This module implements a simple 1-D array type whose only supported operations are "append" (simplelist_Append) and "get element" (simplelist_GetElem). This list should only be used to store read-only elements.

A logical SimpleList object (of type simplelist_t) L, of length n, is a sequence of elements L[1], ..., L[n].

If the library is compiled with pthreads support enabled, then simplelist_t is implemented with some locking support, so that a SimpleList user does not have to explicitly lock the list. Refer to simplelist_Append for more information.

Compile-time control flags:

• OSKI_USE_PTHREADS

Go to the source code of this file.

Data Structures
struct	tagSimplenode_t
	Node in the linked list. More...
struct	tagSimplelist_t
	Simple list object. More...
struct	tagSimplelistIterator_t
	Iterator object for a simple list. More...
Typedefs
typedef tagSimplenode_t	simplenode_t
	Node in the linked list.
typedef tagSimplelist_t	simplelist_t
	Simple list object.
typedef tagSimplelistIterator_t	simplelist_iter_t
	Iterator object for a simple list.
Functions
simplelist_t *	simplelist_Create (void)
	Returns a newly allocated list object.
void	simplelist_Destroy (simplelist_t *L)
	Deallocates memory associated with a simple list.
size_t	simplelist_Append (simplelist_t *L, const void *element)
	Append a new element to the list, and return its list index.
size_t	simplelist_GetLength (const simplelist_t *L)
	Returns the length of the list.
const void *	simplelist_GetElem (const simplelist_t *L, size_t i)
	Returns a given element from the list.
void	simplelist_InitIter (const simplelist_t *L, simplelist_iter_t *i)
	Initialize an iterator.
const void *	simplelist_BeginIter (const simplelist_t *L, simplelist_iter_t *i)
	Initialize an iterator and return the first element.
const void *	simplelist_GetIterObj (const simplelist_iter_t *i)
	Return the object of the current iteration.
size_t	simplelist_GetIterId (const simplelist_iter_t *i)
	Return the index of the object of the current iteration.
const void *	simplelist_NextIter (simplelist_iter_t *i)
	Advances the iterator, and then returns the new iteration object.
const void *	simplelist_GetLastElem (const simplelist_t *L)
	Return the last element in the list.

---

Typedef Documentation

typedef struct tagSimplenode_t simplenode_t

Node in the linked list. A node encapsulates an arbitrary data element, and furthermore contains a pointer to the next element of the list (or NULL if none). Note that the element should logically be read-only.

---

Function Documentation

size_t simplelist_Append (  simplelist_t *  L, const void *  element )

Append a new element to the list, and return its list index. Parameters: [in,out]  L  List object. [in]  element  A pointer to a read-only element to insert. Returns: The index i >= 1 of the new list element. That is, element becomes the logical list element, L[i]. On error, returns 0. In multithreaded environments, calls to simplelist_Append are mutually exclusive. Simultaneous simplelist_GetLength and simplelist_GetElem operations may execute and are considered 'safe' provided they access elements whose index is less than the length of the list at the time of the call to simplelist_Append. Begin mutually exclusive region. End mutually exclusive region.

simplelist_t* simplelist_Create (  void   )

Returns a newly allocated list object. Returns: A newly allocated simple list.

void simplelist_Destroy (  simplelist_t *  L  )

Deallocates memory associated with a simple list. Parameters: [in,out]  L  List object to destroy. In multithreaded environments, the caller MUST ensure that no other threads are executing any operations on L.

const void* simplelist_GetElem (  const simplelist_t *  L, size_t  i )

Returns a given element from the list. Parameters: [in]  L  List object containing elements. [in]  i  Index of item to retrieve, starting at 1 for the first element. If L is invalid or i , then NULL is returned. Otherwise, returns the logical element L[i].

size_t simplelist_GetIterId (  const simplelist_iter_t *  i  )

Return the index of the object of the current iteration. Parameters: [in]  i  Pointer to an initialized iteration object.

const void* simplelist_GetIterObj (  const simplelist_iter_t *  i  )

Return the object of the current iteration. Parameters: [in]  i  Pointer to an initialized iteration object.

size_t simplelist_GetLength (  const simplelist_t *  L  )

Returns the length of the list. Parameters: [in]  L  List object. Returns: Length of the list, or 0 if the list is either empty or NULL.

void simplelist_InitIter (  const simplelist_t *  L, simplelist_iter_t *  i )

Initialize an iterator. Parameters: [in]  L  List over which to iterate. [in,out]  i  Pointer to an uninitialized iteration object.

const void* simplelist_NextIter (  simplelist_iter_t *  i  )

Advances the iterator, and then returns the new iteration object. Parameters: [in,out]  i  Pointer to an initialized iteration object.

---