citem.h File Reference

Detailed Description

This file provides the definitions for creating a data structures that can be contained in a linked lists, containers, trees, etc.

using 'intrusive' linkage. The item to be contained is RESPONSIBLE for providing the memory for the link pointer(s). CAUTION: Since the is only one set of link(s) per structure, the structure can only be in at most ONE list at any given time.

USAGE:

To make a data structure 'listable', the application/developers needs to modify the data structure as follows:

Original structure:
    typedef struct
    {
        int   my_data;
        void* my_ptr;
        ....
    } MyStructure;
 
Linkable structure:
    typedef struct
    {
        CPL_CONTAINTER_ITEM_SLIST;             // Link(s) for container implementation
        int   my_data;
        void* my_ptr;
        ....
    } MyStructure;

NOTES:

1. The above macro MUST be the FIRST field in the data structure.
2. All 'items' must be initialized before be placed in a list
3. Items are NOT type safe!
4. An item can be in at most ONE container at any given time. If an attempt is made to put an item is to multiple containers (at the same time) - the put/insert operation fails

#include <stdbool.h>

Include dependency graph for citem.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	CplContainerItemSListLinkage_T
	Type definition for a singly linked item. More...
struct	CplContainerItemDListLinkage_T
	Type definition for a Doubly linked item. More...

Macros
#define	CPL_CONTAINTER_ITEM_SLIST   CplContainerItemSListLinkage_T __cpl_container_item_slist__
	Single-Link field.
#define	CPL_CONTAINTER_ITEM_DLIST   CplContainerItemDListLinkage_T __cpl_container_item_dlist__
	Double-Link field.

Typedefs
typedef void(*	CplContainerItemFatalErrorCbFunc_T) (void *item, void *currentList, void *newList)
	This type defines the fatal-error-callback function handler.

Functions
void	Cpl_Container_Item_initialize (void *uninitializeItem)
	This method is used to initialize an 'item' instance.
bool	Cpl_Container_Item_markAsContained_ (void *item, void *newContainerPtr)
	This function is private and/or has 'PACKAGE_SCOPE'.
bool	Cpl_Container_Item_isInContainer_ (const void *item, const void *containerPtr)
	This function is private and/or has 'PACKAGE_SCOPE'.
void	Cpl_Container_Item_markAsFree_ (void *item)
	This function is private and/or has 'PACKAGE_SCOPE'.

---

Class Documentation

CplContainerItemSListLinkage_T

struct CplContainerItemSListLinkage_T

Type definition for a singly linked item.

Class Members
void *	containerPtr
void *	nextPtr

CplContainerItemDListLinkage_T

struct CplContainerItemDListLinkage_T

Type definition for a Doubly linked item.

Class Members
void *	containerPtr
void *	nextPtr
void *	prevPtr

Macro Definition Documentation

CPL_CONTAINTER_ITEM_DLIST

#define CPL_CONTAINTER_ITEM_DLIST   CplContainerItemDListLinkage_T __cpl_container_item_dlist__

Double-Link field.

This symbol must be placed as the FIRST entry in a the user's structure that will/can be stored in a container.

NOTE: The item can also be used/contained in a Singly Link list

CPL_CONTAINTER_ITEM_SLIST

#define CPL_CONTAINTER_ITEM_SLIST   CplContainerItemSListLinkage_T __cpl_container_item_slist__

Single-Link field.

This symbol must be placed as the FIRST entry in a the user's structure that will/can be stored in a container.

Typedef Documentation

CplContainerItemFatalErrorCbFunc_T

typedef void(* CplContainerItemFatalErrorCbFunc_T) (void *item, void *currentList, void *newList)

This type defines the fatal-error-callback function handler.

Function Documentation

Cpl_Container_Item_initialize()

void Cpl_Container_Item_initialize

(

void *

uninitializeItem

)

This method is used to initialize an 'item' instance.

The initialization only needs to occur ONCE after the instance has been allocated. ALL ITEMS MUST be initialize prior to placing them in a container.

EXCEPTION: If an item is statically allocated, aka it is in the BSS segment, it does not have be initialize using this method since the C/C++ standard guaranties all data in the BSS segment will be initialized to zero on start-up.

Cpl_Container_Item_isInContainer_()

bool Cpl_Container_Item_isInContainer_	(	const void *	item,
		const void *	containerPtr
	)

This function is private and/or has 'PACKAGE_SCOPE'.

This means that the application should NEVER call/use this functions. The functions are only exposes to simply the implementation of the containers.

This function returns true if the item is in the specified container else false is returned

Cpl_Container_Item_markAsContained_()

bool Cpl_Container_Item_markAsContained_	(	void *	item,
		void *	newContainerPtr
	)

This function is private and/or has 'PACKAGE_SCOPE'.

This means that the application should NEVER call/use this functions. The functions are only exposes to simply the implementation of the containers.

This function is used to mark the item as in-a-container.

Returns true if successful; else false is returned (i.e. the item is already in a container)

Cpl_Container_Item_markAsFree_()

void Cpl_Container_Item_markAsFree_

(

void *

item

)

This function is private and/or has 'PACKAGE_SCOPE'.

This means that the application should NEVER call/use this functions. The functions are only exposes to simply the implementation of the containers.

This function is used to mark the item as 'available', i.e. NOT in a container.