cmlabs::GenericMemoryMap< T, ID > Class Template Reference

Static algorithms shared by all bitfield-indexed maps in the data-maps segment. More...

#include <DataMapsMemory.h>

Static Public Member Functions
static T *	CreateEntry (char *data, ID id, const char *name)
	Reserve entry id with name (status 1).
static T *	CreateFirstFreeEntry (char *data, ID &id, const char *name)
	Reserve the first free id.
static T *	GetEntry (char *data, ID id)
	Fetch the confirmed entry at index id.
static bool	ConfirmEntry (char *data, ID id)
	Mark entry ready (status 2).
static bool	CancelEntry (char *data, ID id)
	Roll back a reserved entry.
static bool	DeleteEntry (char *data, ID id)
	Free the entry and its bit.
static uint64	GetEntryTime (char *data, ID id)
	Creation timestamp of entry id.
static bool	GetEntryName (char *data, ID id, char *name, uint32 maxSize)
	Copy the entry name.
static ID	GetEntryID (char *data, const char *name, bool force=false)
	Case-insensitive reverse lookup: find the id registered under name.
static uint8	LookupEntryID (char *data, const char *name, ID &id)
	Case-insensitive lookup returning the entry's sync status rather than filtering by it.
static uint32	GetCount (char *data)
	Number of entries currently registered in the map (from the header's count field).
static uint32	GetUsage (char *data)
	Approximate bytes in use by entry payloads (count * sizeof(T)); excludes the header and bitfield.
static std::string	PrintAllEntries (char *data)
	Human-readable text dump of all occupied entries, one per line ("id = name (time)"; unconfirmed entries prefixed with '*').
static std::string	PrintAllEntriesHTML (char *data)
	Dump all occupied entries as HTML table rows (no surrounding table element); used by the node's monitoring pages.
static std::string	ToXML (char *data)
	Serialize all occupied entries as XML by delegating to each entry's toXML(), wrapped in the outer element named by T::GetOuterXMLName() with a count attribute.
static bool	WriteAllEntriesToMsg (char *data, DataMessage *msg)
	Serialize all entries into msg.
static bool	WriteAllIDsToMsg (const char *arrayname, char *data, DataMessage *msg)
	Write just names into msg under arrayname.
static uint32	GetCount (char *data)
static T *	CreateEntry (char *data, ID id, const char *name)
	Reserve entry id.
static T *	GetEntry (char *data, ID id)
static bool	DeleteEntry (char *data, ID id)
	Free the entry.
static uint64	GetEntryTime (char *data, ID id)
static const char *	GetEntryName (char *data, ID id, uint32 &size)
static ID	GetEntryID (char *data, const char *name)

Detailed Description

template<typename T, typename ID>
class cmlabs::GenericMemoryMap< T, ID >

Static algorithms shared by all bitfield-indexed maps in the data-maps segment.

Legacy generic map algorithms (3-parameter variant with unused KEY type).

Template Parameters

T	Entry struct (TypeMapEntry, TagMapEntry, ...),
ID	its id type. All functions take the raw mapped map address (data = GenericMapHeader*); callers must hold the segment mutex. Returned entry pointers point into shared memory and are only valid while the segment mapping and lock are held. Implemented in MemoryMaps.tpl.h.
T	Entry type.
ID	Id type.
KEY	Unused key type (historical). Superseded by the 2-parameter GenericMemoryMap in DataMapsMemory.h; bodies live in MemoryMaps.tpl.h. Entry pointers returned point into shared memory.

Definition at line 379 of file DataMapsMemory.h.

Member Function Documentation

CancelEntry()

template<typename T, typename ID>

bool cmlabs::GenericMemoryMap< T, ID >::CancelEntry ( char * data, ID id )

static

Roll back a reserved entry.

Roll back a reserved-but-unconfirmed entry (status 1 or less), clearing its status and timestamp so the slot can be reused.

Returns

true on success.

true if the entry was cancelled or was already empty; false if the entry has already been confirmed (status 2); confirmed entries must be removed with DeleteEntry() instead.

Note

Does not clear the occupancy bit; the slot is recycled via the id/time checks in CreateEntry().

Definition at line 265 of file MemoryMaps.tpl.h.

References cmlabs::GenericMapHeader::bitFieldSize, and cmlabs::GenericMapHeader::size.

Referenced by cmlabs::DataMapsMemory::cancelContextLevelID(), cmlabs::DataMapsMemory::cancelCrankID(), cmlabs::DataMapsMemory::cancelTagID(), and cmlabs::DataMapsMemory::cancelTypeLevelID().

ConfirmEntry()

template<typename T, typename ID>

bool cmlabs::GenericMemoryMap< T, ID >::ConfirmEntry ( char * data, ID id )

static

Mark entry ready (status 2).

Commit a reserved entry: promote status from 1 (assigned) to 2 (ready).

Returns

true on success.

Second phase of the two-phase id allocation used for cluster-wide agreement: once confirmed, the entry becomes visible to GetEntry()/GetEntryID() in every process.

Returns

true if the entry existed and was confirmed (or already ready); false on a stale/invalid id.

Definition at line 237 of file MemoryMaps.tpl.h.

References cmlabs::GenericMapHeader::bitFieldSize, and cmlabs::GenericMapHeader::size.

Referenced by cmlabs::DataMapsMemory::confirmContextLevelID(), cmlabs::DataMapsMemory::confirmCrankID(), cmlabs::DataMapsMemory::confirmTagID(), and cmlabs::DataMapsMemory::confirmTypeLevelID().

CreateEntry() [1/2]

template<typename T, typename ID>

T * cmlabs::GenericMemoryMap< T, ID >::CreateEntry ( char * data, ID id, const char * name )

static

Reserve entry id with name (status 1).

Reserve the map entry at index id and stamp it with name.

Returns

Entry or NULL.

Sets the occupancy bit, initialises the entry (status 1 = assigned/unconfirmed, creation time = now) and increments the map's count. If the slot is already occupied by an entry with the same name, that existing entry is returned instead (idempotent re-registration); a name clash on an occupied slot returns NULL.

Parameters

data	Raw mapped map region (GenericMapHeader at offset 0).
id	Fixed index to reserve; must be less than GenericMapHeader::maxID.
name	Entry name (truncated to MAXKEYNAMELEN); may be NULL to skip naming.

Returns

Pointer to the entry inside shared memory, or NULL on failure.

Warning

The returned pointer aliases shared memory: it is only valid while the segment mapping is unchanged and the caller holds the segment's cross-process mutex. Follow up with ConfirmEntry() (commit) or CancelEntry() (roll back); GetEntry() ignores entries still in status 1.

Definition at line 46 of file MemoryMaps.tpl.h.

References cmlabs::GenericMapHeader::bitFieldSize, BITOCCUPIED, cmlabs::GenericMapHeader::count, cmlabs::utils::GetBit(), GetEntry(), cmlabs::GetTimeNow(), cmlabs::GenericMapHeader::maxID, MAXKEYNAMELEN, cmlabs::utils::SetBit(), cmlabs::GenericMapHeader::size, and cmlabs::utils::strcpyavail().

Referenced by cmlabs::DataMapsMemory::createNewContextLevel(), cmlabs::DataMapsMemory::createNewCrank(), cmlabs::DataMapsMemory::createNewTag(), and cmlabs::DataMapsMemory::createNewTypeLevel().

CreateEntry() [2/2]

template<typename T, typename ID>

T * cmlabs::GenericMemoryMap< T, ID >::CreateEntry ( char * data, ID id, const char * name )

static

Reserve entry id.

Returns

Entry or NULL.

CreateFirstFreeEntry()

template<typename T, typename ID>

T * cmlabs::GenericMemoryMap< T, ID >::CreateFirstFreeEntry ( char * data, ID & id, const char * name )

static

Reserve the first free id.

Reserve the lowest free index in the map and stamp it with name.

Parameters

data	Mapped map region.
id	Receives it.
name	Entry name.

Returns

Entry or NULL.

Same two-phase semantics as CreateEntry(), but the index is chosen by scanning the occupancy bitfield for the first free bit instead of being supplied by the caller. Used when the id value carries no meaning and only uniqueness matters.

Operates on the raw mapped map region passed in data. Receives the allocated index in id; name is the entry name (may be NULL).

Returns

Pointer into shared memory (valid only under the segment mutex), or NULL if the map is full or the slot is corrupt.

Note

Not atomic across processes by itself; the caller must hold the segment mutex or two processes may race for the same free bit.

Definition at line 117 of file MemoryMaps.tpl.h.

References cmlabs::GenericMapHeader::bitFieldSize, BITOCCUPIED, cmlabs::GenericMapHeader::count, cmlabs::utils::GetFirstFreeBitLoc(), cmlabs::GetTimeNow(), cmlabs::GenericMapHeader::maxID, MAXKEYNAMELEN, cmlabs::utils::SetBit(), cmlabs::GenericMapHeader::size, and cmlabs::utils::strcpyavail().

Referenced by cmlabs::DataMapsMemory::createNewRequest().

DeleteEntry() [1/2]

template<typename T, typename ID>

bool cmlabs::GenericMemoryMap< T, ID >::DeleteEntry ( char * data, ID id )

static

Free the entry and its bit.

Free the entry at index id.

Returns

true on success.

Verifies the slot actually holds entry id (matching id field and non-zero time) before zeroing its timestamp, decrementing the count and clearing the occupancy bit. The entry bytes themselves are not wiped; the slot may be recycled by a later CreateEntry()/CreateFirstFreeEntry().

Returns

true if the entry existed and was freed; false on a stale/invalid id.

Note

Caller must hold the segment's cross-process mutex.

Definition at line 171 of file MemoryMaps.tpl.h.

References cmlabs::GenericMapHeader::bitFieldSize, BITFREE, cmlabs::GenericMapHeader::count, cmlabs::utils::SetBit(), and cmlabs::GenericMapHeader::size.

Referenced by cmlabs::MemoryMaps::DeleteContextLevel(), cmlabs::MemoryMaps::DeleteContextLevel(), cmlabs::DataMapsMemory::deleteContextLevel(), cmlabs::DataMapsMemory::deleteContextLevel(), cmlabs::MemoryMaps::DeleteCrank(), cmlabs::MemoryMaps::DeleteCrank(), cmlabs::DataMapsMemory::deleteCrank(), cmlabs::DataMapsMemory::deleteCrank(), cmlabs::DataMapsMemory::deleteRequest(), cmlabs::DataMapsMemory::deleteTag(), cmlabs::DataMapsMemory::deleteTag(), cmlabs::MemoryMaps::DeleteTopic(), cmlabs::MemoryMaps::DeleteTopic(), cmlabs::MemoryMaps::DeleteTypeLevel(), cmlabs::MemoryMaps::DeleteTypeLevel(), cmlabs::DataMapsMemory::deleteTypeLevel(), and cmlabs::DataMapsMemory::deleteTypeLevel().

DeleteEntry() [2/2]

template<typename T, typename ID>

bool cmlabs::GenericMemoryMap< T, ID >::DeleteEntry ( char * data, ID id )

static

Free the entry.

Returns

true on success.

GetCount() [1/2]

template<typename T, typename ID>

uint32 cmlabs::GenericMemoryMap< T, ID >::GetCount ( char * data )

static

Number of entries currently registered in the map (from the header's count field).

Returns

Number of entries in use.

Definition at line 480 of file MemoryMaps.tpl.h.

References cmlabs::GenericMapHeader::count.

Referenced by cmlabs::DataMapsMemory::getRequestCount().

GetCount() [2/2]

template<typename T, typename ID>

uint32 cmlabs::GenericMemoryMap< T, ID >::GetCount ( char * data )

static

Returns

Number of entries in use.

GetEntry() [1/2]

template<typename T, typename ID>

T * cmlabs::GenericMemoryMap< T, ID >::GetEntry ( char * data, ID id )

static

Fetch the confirmed entry at index id.

Returns

Entry id or NULL if free/out of range.

Only returns entries that are fully committed (status greater than 1, i.e. past ConfirmEntry()); entries still in the reserved/unconfirmed state are treated as absent. This is what makes the two-phase create-then-confirm protocol race-safe for readers.

Returns

Pointer into shared memory (valid only under the segment mutex and while the mapping is unchanged), or NULL if free, unconfirmed or out of range.

Definition at line 213 of file MemoryMaps.tpl.h.

References cmlabs::GenericMapHeader::bitFieldSize, and cmlabs::GenericMapHeader::size.

Referenced by CreateEntry(), cmlabs::DataMapsMemory::createNewTypeLevel(), cmlabs::DataMapsMemory::getCrankCompID(), cmlabs::DataMapsMemory::getCrankFunction(), cmlabs::DataMapsMemory::getCrankLanguage(), cmlabs::DataMapsMemory::getCrankLibraryFilename(), cmlabs::DataMapsMemory::getCrankScript(), GetEntryName(), GetEntryTime(), cmlabs::DataMapsMemory::getRequestInfo(), cmlabs::DataMapsMemory::getRequestStatus(), cmlabs::DataMapsMemory::setRequestStatus(), cmlabs::DataMapsMemory::setRequestStatus(), and cmlabs::DataMapsMemory::waitForRequestReply().

GetEntry() [2/2]

template<typename T, typename ID>

T * cmlabs::GenericMemoryMap< T, ID >::GetEntry ( char * data, ID id )

static

Returns

Entry id or NULL.

GetEntryID() [1/2]

template<typename T, typename ID>

ID cmlabs::GenericMemoryMap< T, ID >::GetEntryID ( char * data, const char * name )

static

Returns

Id for name.

GetEntryID() [2/2]

template<typename T, typename ID>

ID cmlabs::GenericMemoryMap< T, ID >::GetEntryID ( char * data, const char * name, bool force = false )

static

Case-insensitive reverse lookup: find the id registered under name.

Returns

Id for name (force also matches unconfirmed).

Linearly scans every entry slot (freed slots keep their bytes but are filtered by status), so cost is O(maxID); hold the segment mutex while calling.

Parameters

data	Raw mapped map region.
name	Name to look up (case-insensitive).
force	When true, also match reserved-but-unconfirmed entries (status 1); used during id negotiation.

Returns

The entry's id, or 0 if not found.

Note

These maps rely on id 0 never being handed out for name-addressed entries, since 0 doubles as the not-found value.

Definition at line 311 of file MemoryMaps.tpl.h.

References cmlabs::GenericMapHeader::bitFieldSize, cmlabs::GenericMapHeader::size, and stricmp.

Referenced by cmlabs::DataMapsMemory::createNewContextLevel(), cmlabs::DataMapsMemory::createNewCrank(), cmlabs::DataMapsMemory::createNewTag(), cmlabs::DataMapsMemory::createNewTypeLevel(), cmlabs::MemoryMaps::DeleteContextLevel(), cmlabs::DataMapsMemory::deleteContextLevel(), cmlabs::MemoryMaps::DeleteCrank(), cmlabs::DataMapsMemory::deleteCrank(), cmlabs::DataMapsMemory::deleteTag(), cmlabs::MemoryMaps::DeleteTopic(), cmlabs::MemoryMaps::DeleteTypeLevel(), cmlabs::DataMapsMemory::deleteTypeLevel(), cmlabs::MemoryMaps::GetContextLevelID(), cmlabs::DataMapsMemory::getContextLevelID(), cmlabs::MemoryMaps::GetCrankID(), cmlabs::DataMapsMemory::getCrankID(), cmlabs::DataMapsMemory::getTagID(), cmlabs::MemoryMaps::GetTopicID(), cmlabs::MemoryMaps::GetTypeLevelID(), and cmlabs::DataMapsMemory::getTypeLevelID().

GetEntryName() [1/2]

template<typename T, typename ID>

bool cmlabs::GenericMemoryMap< T, ID >::GetEntryName ( char * data, ID id, char * name, uint32 maxSize )

static

Copy the entry name.

Copy the name of confirmed entry id into the caller's buffer.

Returns

true if found.

Parameters

data	Raw mapped map region.
id	Entry index.
name	Destination buffer (caller-owned).
maxSize	Buffer capacity in bytes.

Returns

true if the entry exists (confirmed) and the name was copied.

Definition at line 292 of file MemoryMaps.tpl.h.

References GetEntry(), and cmlabs::utils::strcpyavail().

Referenced by cmlabs::MemoryMaps::GetContextLevelName(), cmlabs::DataMapsMemory::getContextLevelName(), cmlabs::MemoryMaps::GetCrankName(), cmlabs::DataMapsMemory::getCrankName(), cmlabs::DataMapsMemory::getTagName(), cmlabs::MemoryMaps::GetTopicName(), cmlabs::MemoryMaps::GetTypeLevelName(), and cmlabs::DataMapsMemory::getTypeLevelName().

GetEntryName() [2/2]

template<typename T, typename ID>

const char * cmlabs::GenericMemoryMap< T, ID >::GetEntryName ( char * data, ID id, uint32 & size )

static

Returns

Name pointer into shared memory, or NULL.

GetEntryTime() [1/2]

template<typename T, typename ID>

uint64 cmlabs::GenericMemoryMap< T, ID >::GetEntryTime ( char * data, ID id )

static

Creation timestamp of entry id.

Returns

Entry creation time, 0 if absent.

Time (µs) the entry was created, or 0 if the entry is absent/unconfirmed.

Definition at line 196 of file MemoryMaps.tpl.h.

References GetEntry().

Referenced by cmlabs::DataMapsMemory::getContextLevelCreateTime(), cmlabs::DataMapsMemory::getCrankCreateTime(), cmlabs::DataMapsMemory::getTagCreateTime(), and cmlabs::DataMapsMemory::getTypeLevelCreateTime().

GetEntryTime() [2/2]

template<typename T, typename ID>

uint64 cmlabs::GenericMemoryMap< T, ID >::GetEntryTime ( char * data, ID id )

static

Returns

Creation time, 0 if absent.

GetUsage()

template<typename T, typename ID>

uint32 cmlabs::GenericMemoryMap< T, ID >::GetUsage ( char * data )

static

Approximate bytes in use by entry payloads (count * sizeof(T)); excludes the header and bitfield.

Returns

Bytes in use by the map.

Definition at line 489 of file MemoryMaps.tpl.h.

LookupEntryID()

template<typename T, typename ID>

uint8 cmlabs::GenericMemoryMap< T, ID >::LookupEntryID ( char * data, const char * name, ID & id )

static

Case-insensitive lookup returning the entry's sync status rather than filtering by it.

Returns

Status (0 absent, 1 in-sync, 2 ready); id receives the id.

Unlike GetEntryID(), this reports reserved entries too, letting callers distinguish "absent" from "being negotiated" from "ready".

Parameters

data	Raw mapped map region.
name	Name to look up (case-insensitive).
id	Receives the matching entry's id when found.

Returns

0 if no entry has name, 1 if reserved/in-sync, 2 if confirmed/ready.

Definition at line 339 of file MemoryMaps.tpl.h.

References cmlabs::GenericMapHeader::bitFieldSize, cmlabs::GenericMapHeader::size, and stricmp.

Referenced by cmlabs::DataMapsMemory::lookupContextLevelID(), cmlabs::DataMapsMemory::lookupCrankID(), cmlabs::DataMapsMemory::lookupTagID(), and cmlabs::DataMapsMemory::lookupTypeLevelID().

PrintAllEntries()

template<typename T, typename ID>

std::string cmlabs::GenericMemoryMap< T, ID >::PrintAllEntries ( char * data )

static

Human-readable text dump of all occupied entries, one per line ("id = name (time)"; unconfirmed entries prefixed with '*').

Returns

Text dump of all entries.

Diagnostic use.

Definition at line 361 of file MemoryMaps.tpl.h.

References cmlabs::GenericMapHeader::bitFieldSize, cmlabs::PrintTimeString(), cmlabs::GenericMapHeader::size, and cmlabs::utils::StringFormat().

Referenced by cmlabs::DataMapsMemory::printAllContexts(), and cmlabs::DataMapsMemory::printAllTypes().

PrintAllEntriesHTML()

template<typename T, typename ID>

std::string cmlabs::GenericMemoryMap< T, ID >::PrintAllEntriesHTML ( char * data )

static

Dump all occupied entries as HTML table rows (no surrounding table element); used by the node's monitoring pages.

Returns

HTML dump of all entries.

Definition at line 384 of file MemoryMaps.tpl.h.

References cmlabs::GenericMapHeader::bitFieldSize, cmlabs::PrintTimeString(), cmlabs::GenericMapHeader::size, and cmlabs::utils::StringFormat().

Referenced by cmlabs::DataMapsMemory::printFriendlyHTML().

ToXML()

template<typename T, typename ID>

std::string cmlabs::GenericMemoryMap< T, ID >::ToXML ( char * data )

static

Serialize all occupied entries as XML by delegating to each entry's toXML(), wrapped in the outer element named by T::GetOuterXMLName() with a count attribute.

Returns

XML dump of all entries.

Definition at line 407 of file MemoryMaps.tpl.h.

References cmlabs::GenericMapHeader::bitFieldSize, cmlabs::GenericMapHeader::size, and cmlabs::utils::StringFormat().

Referenced by cmlabs::DataMapsMemory::toXML().

WriteAllEntriesToMsg()

template<typename T, typename ID>

bool cmlabs::GenericMemoryMap< T, ID >::WriteAllEntriesToMsg ( char * data, DataMessage * msg )

static

Serialize all entries into msg.

Serialize all occupied entries (full fields) into msg via each entry's writeToMsg(), indexed 0..n-1.

Returns

true on success.

Used to ship whole maps to remote nodes for syncing.

Returns

true if every entry was written; aborts and returns false on the first failure.

Definition at line 458 of file MemoryMaps.tpl.h.

References cmlabs::GenericMapHeader::bitFieldSize, and cmlabs::GenericMapHeader::size.

Referenced by cmlabs::DataMapsMemory::writeContextLevelsToMsg(), cmlabs::DataMapsMemory::writeCranksToMsg(), cmlabs::DataMapsMemory::writeTagsToMsg(), and cmlabs::DataMapsMemory::writeTypeLevelsToMsg().

WriteAllIDsToMsg()

template<typename T, typename ID>

bool cmlabs::GenericMemoryMap< T, ID >::WriteAllIDsToMsg ( const char * arrayname, char * data, DataMessage * msg )

static

Write just names into msg under arrayname.

Write just the names of all occupied entries into msg as array arrayname, via each entry's writeIDToMsg().

Returns

true on success.

Used for lightweight cluster synchronisation.

Returns

true if every entry was written; aborts and returns false on the first failure.

Definition at line 434 of file MemoryMaps.tpl.h.

References cmlabs::GenericMapHeader::bitFieldSize, and cmlabs::GenericMapHeader::size.

Referenced by cmlabs::DataMapsMemory::writeIDsToMsg().

---

The documentation for this class was generated from the following files:

• /home/ubuntu/c/partner/psyclone2/CMSDK/include/DataMapsMemory.h
• /home/ubuntu/c/partner/psyclone2/CMSDK/include/MemoryMaps.h
• /home/ubuntu/c/partner/psyclone2/CMSDK/include/MemoryMaps.tpl.h