cmlabs::MessageIndex Class Reference

Multi-key in-memory index and lifetime manager for DataMessages. More...

#include <MessageIndex.h>

Public Member Functions
	MessageIndex ()
	Create an empty index with no extra index keys and no file storage.
	~MessageIndex ()
	Destroys the index and deletes all messages it still holds.
bool	setDefaultTTL (uint64 defaultTTL)
	Set the TTL applied to messages that carry none of their own.
bool	addIndexKey (const char *key, uint8 type)
	Start indexing messages by the value of a named user entry.
bool	removeIndexKey (const char *key, uint8 type)
	Remove a previously added index key (the index over that entry is dropped; the messages themselves remain).
bool	setFileStorage (const char *dir, uint32 buffertime, const char *indexfilename="index.db")
	Enable file-backed storage of indexed messages.
bool	addMessage (DataMessage *msg)
	Add a message to the index; the index TAKES OWNERSHIP of msg and will delete it on expiry.
char *	queryMessages (RetrieveSpec *spec, uint32 &size, uint32 &count)
	Execute a retrieval query and return matching messages as one flat buffer.
uint32	getCount ()
bool	doMaintenance ()
	Perform periodic housekeeping: evict expired messages (per TTL/EOL) and flush file storage buffers.

Static Public Member Functions
static bool	UnitTest ()
	Run the built-in self test.

Detailed Description

Multi-key in-memory index and lifetime manager for DataMessages.

Ownership: addMessage() takes ownership of the message — the index deletes it when it expires or the index is destroyed. Results returned by queryMessages() are a newly allocated flat buffer of message copies owned by the caller.

Warning

Not internally synchronised; callers (e.g. the whiteboard component) must serialise access from multiple threads.

Definition at line 33 of file MessageIndex.h.

Constructor & Destructor Documentation

MessageIndex()

cmlabs::MessageIndex::MessageIndex

(

)

Create an empty index with no extra index keys and no file storage.

Definition at line 11 of file MessageIndex.cpp.

References cmlabs::GetTimeNow(), and PSYMINUTE.

Referenced by UnitTest().

~MessageIndex()

cmlabs::MessageIndex::~MessageIndex

(

)

Destroys the index and deletes all messages it still holds.

Definition at line 20 of file MessageIndex.cpp.

Member Function Documentation

addIndexKey()

bool cmlabs::MessageIndex::addIndexKey	(	const char *	key,
		uint8	type )

Start indexing messages by the value of a named user entry.

Subsequently added messages containing this entry become retrievable by value/range queries on it.

Parameters

key	user entry name to index on
type	entry interpretation: INDEX_TIME, INDEX_STRING, INDEX_INTEGER or INDEX_FLOAT

Returns

true if successful

Definition at line 47 of file MessageIndex.cpp.

References INDEX_FLOAT, INDEX_INTEGER, INDEX_STRING, INDEX_TIME, and stricmp.

Referenced by UnitTest().

addMessage()

bool cmlabs::MessageIndex::addMessage

(

DataMessage *

msg

)

Add a message to the index; the index TAKES OWNERSHIP of msg and will delete it on expiry.

Parameters

msg	the message to index

Returns

true if successful

Definition at line 105 of file MessageIndex.cpp.

References doMaintenance(), cmlabs::DataMessage::getCreatedTime(), cmlabs::DataMessage::getEOL(), cmlabs::GetTimeAgeMS(), cmlabs::DataMessage::getTTL(), and cmlabs::DataMessage::getType().

Referenced by UnitTest().

doMaintenance()

bool cmlabs::MessageIndex::doMaintenance

(

)

Perform periodic housekeeping: evict expired messages (per TTL/EOL) and flush file storage buffers.

Call regularly, e.g. once per second.

Returns

true if successful

Definition at line 219 of file MessageIndex.cpp.

References cmlabs::GetTimeNow().

Referenced by addMessage(), and queryMessages().

getCount()

uint32 cmlabs::MessageIndex::getCount

(

)

Returns

the number of messages currently held by the index.

Definition at line 101 of file MessageIndex.cpp.

queryMessages()

char * cmlabs::MessageIndex::queryMessages	(	RetrieveSpec *	spec,
		uint32 &	size,
		uint32 &	count )

Execute a retrieval query and return matching messages as one flat buffer.

The buffer contains the binary blocks of the matching messages back-to-back and is owned by the caller (delete[]).

Parameters

spec	the retrieval specification (type, key, ranges, maxcount, maxage, ...)
size	receives the byte size of the returned buffer
count	receives the number of messages in the buffer

Returns

the buffer, or NULL if nothing matched

Definition at line 129 of file MessageIndex.cpp.

References doMaintenance(), cmlabs::RetrieveSpec::endFloat, cmlabs::RetrieveSpec::endInt, cmlabs::RetrieveSpec::endString, cmlabs::RetrieveSpec::endTime, FLOAT64_NOVALUE, cmlabs::RetrieveSpec::from, cmlabs::GetTimeAgeMS(), INDEX_FLOAT, INDEX_INTEGER, INDEX_STRING, INDEX_TIME, INT64_NOVALUE, cmlabs::RetrieveSpec::key, cmlabs::RetrieveSpec::keytype, cmlabs::RetrieveSpec::maxage, cmlabs::RetrieveSpec::maxcount, queryMessages(), cmlabs::RetrieveSpec::startFloat, cmlabs::RetrieveSpec::startInt, cmlabs::RetrieveSpec::startString, cmlabs::RetrieveSpec::startTime, stricmp, cmlabs::RetrieveSpec::to, and cmlabs::RetrieveSpec::type.

Referenced by queryMessages(), and UnitTest().

removeIndexKey()

bool cmlabs::MessageIndex::removeIndexKey	(	const char *	key,
		uint8	type )

Remove a previously added index key (the index over that entry is dropped; the messages themselves remain).

Parameters

key	user entry name
type	the type the key was registered with

Returns

true if successful

Definition at line 72 of file MessageIndex.cpp.

References INDEX_FLOAT, INDEX_INTEGER, INDEX_STRING, INDEX_TIME, and stricmp.

setDefaultTTL()

bool cmlabs::MessageIndex::setDefaultTTL

(

uint64

defaultTTL

)

Set the TTL applied to messages that carry none of their own.

Parameters

defaultTTL

default time-to-live in microseconds

Returns

true if successful

Definition at line 42 of file MessageIndex.cpp.

setFileStorage()

bool cmlabs::MessageIndex::setFileStorage	(	const char *	dir,
		uint32	buffertime,
		const char *	indexfilename = "index.db" )

Enable file-backed storage of indexed messages.

Parameters

dir	directory to store message files in
buffertime	how long (ms) messages are buffered before being flushed
indexfilename	name of the index database file inside dir

Returns

true if successful

Definition at line 94 of file MessageIndex.cpp.

UnitTest()

bool cmlabs::MessageIndex::UnitTest ( )

static

Run the built-in self test.

Returns

true if all tests pass.

Definition at line 566 of file MessageIndex.cpp.

References addIndexKey(), addMessage(), DATAMESSAGEID, cmlabs::unittest::detail(), cmlabs::unittest::fail(), cmlabs::DataMessage::getInt(), GetObjID, cmlabs::DataMessage::getSize(), cmlabs::GetTimeNow(), INDEX_TIME, cmlabs::RetrieveSpec::key, cmlabs::RetrieveSpec::keytype, cmlabs::RetrieveSpec::maxage, cmlabs::RetrieveSpec::maxcount, MAXKEYNAMELEN, MessageIndex(), cmlabs::unittest::metric(), cmlabs::unittest::progress(), queryMessages(), cmlabs::DataMessage::setCreatedTime(), cmlabs::DataMessage::setInt(), cmlabs::DataMessage::setTTL(), cmlabs::utils::Sleep(), and cmlabs::utils::strcpyavail().

Referenced by cmlabs::Register_MessageIndex_Tests().

---

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

• /home/ubuntu/c/partner/psyclone2/CMSDK/include/MessageIndex.h
• /home/ubuntu/c/partner/psyclone2/CMSDK/src/MessageIndex.cpp