#include <cascade/interprocess/CascadeSharedList.h>
Inheritance diagram for CascadeSharedList:
Public Types | |
| typedef void | Entry |
| typedef bool() | EnumProc (Entry *pEnry, void *pClientData) |
| enum | { kMaxHeaderSize = 0xF000, kMaxEntrySize = 0xF000, kMaxEntries = 0xF000 } |
Public Member Functions | |
| CascadeSharedList () | |
| virtual | ~CascadeSharedList () |
| bool | Open (const char *pName, u16 nHeaderSize, u16 nEntrySize, u16 nMaxEntries, bool bCreateIfNecessary) |
| bool | Close () |
| bool | MapLock () |
| bool | Unlock () |
| bool | InsertAtHead (void *pData) |
| bool | AddToTail (void *pData) |
| bool | Insert (void *pData, Entry *pEntryToInsertBefore) |
| u16 | GetNumEntries () |
| u16 | GetMaxEntries () |
| u16 | GetNumEntriesWatermark () |
| Entry * | GetFirstEntry () |
| Entry * | GetLastEntry () |
| Entry * | GetNextEntry (Entry *pEntry) |
| Entry * | GetPrevEntry (Entry *pEntry) |
| int | GetEntryPID (Entry *pEntry) |
| void | ResetEntryPID (Entry *pEntry, int nPID) |
| bool | IsStalePIDEntry (Entry *pEntry) |
| bool | MoveEntry (Entry *pEntry, Entry *pEntryToMoveBefore) |
| bool | MoveEntryToHead (Entry *pEntry) |
| bool | MoveEntryToTail (Entry *pEntry) |
| bool | RemoveEntry (Entry *pEntry) |
| void | PurgeDeadPIDEntries () |
| void * | GetListHeader () |
| bool | Enumerate (EnumProc *pEnumProc, void *pClientData) |
| bool | PIDPurgeEnumerate (EnumProc *pEnumProc, void *pClientData) |
CascadeSharedList provides a named doubly-linked list in shared memory with an optional list-header and optional automatic purging of list entries when the process that added the entry dies.
CascadeSharedList is based on CascadeSharedMemZone.
|
|
the type of a list entry CascadeSharedList returns Entry *'s to you the client. These Entry *'s are pointers to copies of data that you've added to the list. These copies are owned and managed by CascadeSharedList and are only valid while the list is MapLocked. You may cast these pointers to your client data type, but be advised if you want to use the data beyond the lifetime of when you have the list MapLocked you must copy the data.
|
|
|
Callback function for enumerating entries in the list Clients provide their own EnumProc to the Enumerate() and PIDPurgeEnumerate() functions. Your custom EnumProc will get called back by these functions, one for each qualified entry in the list.
|
|
|
|
|
|
the default constructor - lightweight This default constructor is lightweight. |
|
|
destructor This destructor will unlock and close the SharedMemZone if necessary. |
|
|
adds data to the tail of the list AddToTail() makes a copy of *pData (in the amount of bytes that the list was opened with), and makes an Entry out of it and adds it to the end of the list returning true if successful, false otherwise. Note that if you modify *pData after adding it to the list, it doesn't modify the copy in the list.
|
|
|
closes the SharedList Call Close() to close a previously opened shared list. When the last handle to a shared list is closed, the operating system shared memory object is destroyed. This function is provided for convenience - the destructor ~CascadeSharedList() will automatically Close() the shared list if it is still open when the destructor is called. Close() will automatically unlock the shared list if it is map-locked, but good programming practice dictates that you should unlock the shared memory zone yourself as soon as you are done using it.
|
|
||||||||||||
|
enumerates the entries in the list Enumerate() will enumerate through the entries in the list calling *pEnumProc for each entry encountered. Clients should return true from their enum procs to continue enumeration, false to abort enumeration. Enumerate() returns true if the enumeration was carried to completion, false if it was aborted.
|
|
|
gets the PID of the process that added the entry to the list GetEntryPID() returns the PID of the process that added the entry to the list.
|
|
|
gets the first entry in the list GetFirstEntry() returns the Entry * of the first entry in the list or NULL if the list is empty.
|
|
|
gets the last entry in the list GetLastEntry() returns the Entry * of the last entry in the list or NULL if the list is entry.
|
|
|
gets a pointer to the header of the list GetListHeader() returns a pointer to the memory area in the shared memory zone for you, the client's list header. This pointer is only valid while you have the list map-locked and points to the number of bytes passed in as the value of the paramter nHeaderSize to the Open() function. This list header is initialized to all zeros when the list is first created. GetListHeader() returns NULL if the list is not map-locked when GetListHeader() is called, NULL also if the client specified a size of zero bytes for his list header.
|
|
|
gets the maximum number of entries the list can hold GetMaxEntries() returns the maximum number of entries that the list can hold.
|
|
|
gets the next entry in the list GetNextEntry() returns the Entry * of the next entry in the list after pEntry or NULL if pEntry is the last entry in the list.
|
|
|
gets the number of entries in the list GetNumEntries() returns the number of entries in the list.
|
|
|
gets the maximum number of entries the list has actually held GetNumEntriesWatermark() returns the highest number of entries (the watermark) that the list has ever held.
|
|
|
gets the previous entry in the list GetPrevEntry() returns the Entry * of the previous entry in the list before pEntry or NULL if pEntry is the first entry in the list.
|
|
||||||||||||
|
inserts data at a specific point in the list Insert() makes a copy of *pData (in the amount of bytes that the list was opened with), and makes an Entry out of it and inserts it in the list immediately before the entry identified by pEntryToInsertBefore, returning true if successful, false otherwise. See the functions below that return Entry *'s to get a valid Entry * you can use as the argument for pEntryToInsertToBefore. Note that if you modify *pData after inserting it into the list, it doesn't modify the copy in the list.
|
|
|
inserts data at the head of the list InsertAtHead() makes a copy of *pData (in the amount of bytes that the list was opened with), and makes an Entry out of it and inserts it at the head of the list returning true if successful, false otherwise. Note that if you modify *pData after inserting it into the list, it doesn't modify the copy in the list.
|
|
|
determines whether or not the process that added the entry to the list is still running IsStalePIDEntry() returns true if the entry referred to by pEntry has a stale PID, false if it does not have a stale pid. (An entry has a stale pid if the process that added the entry to the list no longer exists).
|
|
|
locks and maps the shared list into your processes' address space Call MapLock() to lock the shared list into your process' memory space. None of the list accessor functions will work unless it is maplocked successfully.
|
|
||||||||||||
|
moves an entry to a specific point in th elist MoveEntry() moves pEntry to the position in the list before pEntryToMoveBefore returning true if successful, false otherwise. (false is only returned if the parameters passed in are bad).
|
|
|
moves an entry to the head of the list MoveEntryToHead() moves the entry pEntry to the head of the list returning true if successful, false otherwise.
|
|
|
moves an entry to the tail of the list MoveEntryToTail() moves the entry pEntry to the tail of the list returning true if successful, false otherwise.
|
|
||||||||||||||||||||||||
|
opens a SharedList Open() opens the a handle to the shared list named pName. nHeaderSize specifies an optional size for a list header - memory stored in the shared memory zone along with the list, but not considered an element of the list. The client (you) can access this memory by calling GetListHeader() below. Valid values for nHeaderSize are [0..kMaxHeaderSize]. nEntrySize specifies the size of the entries in the doubly-linked list. This size is the size of the data to be stored in the list. It is exclusive of list node data which is handled internally by CascadeSharedList and need not concern clients. Valid values for nEntrySize are [1..kMaxEntrySize]. nMaxEntries specifies the maximum number of entries that may be stored in the list. Initially the list starts out empty, and may only grow up to nMaxEntries number of elements. Valid values for nMaxEntries are [1..kMaxEntries]. bCreateIfNecessary - if bCreateIfNecessary is true, the shared list will be created if it doesn't already exist (in shared memory). If bCreateIfNecessary is false, the call to Open() will fail unless the list already exists in shared memory. Open() returns true if successful, false otherwise. Open() will return false if the named list already exists but different parameters were specified than that of the original call to Open() that caused the list to be created.
|
|
||||||||||||
|
enumerates the entries in the list skipping over and removing stale entries PIDPurgeEnumerate() will enumerate through the entries in the list calling *pEnumProc for each entry encountered that does not have a stale PID. Entries that do have stale pids (their adding processes have since died) will be purged from the list during enumeration. Clients should return true from their enum procs to continue enumeration, false to abort enumeration. PIDPurgeEnumerate() returns true if the enumeration was carried to completion, false if it was aborted.
|
|
|
removes all entries that were added by processes that no longer exist PurgeDeadPIDEntries() will iterate through the list, manually removing all entries that were added by processes that no longer exist. |
|
|
removes an entry from the list RemoveEntry() removes the entry pEntry from the list. pEntry must not be accessed by you the client after RemoveEntry returns. RemoveEntry() returns true if successful, false otherwise. false is only returned if a bad pEntry parameter is passed in.
|
|
||||||||||||
|
resets the PID the entry is marked with ResetEntryPID() resets (reassigns) the PID of the process that added the entry to the list.
|
|
|
unlocks the shared list Call Unlock() to unmap and release the shared list. Calls to MapLock() may nest so be sure there is a corresponding call to Unlock() for every call to MapLock().
|
1.4.1