The message manager is a data structure that can be used to put together runtime systems for languages that support tag-based message retrieval.
The purpose of the message manager is to store, index, and retrieve messages according to a set of integer tags. It provides functions to create tables, functions to insert messages into tables (specifying their tags), and functions to selectively retrieve messages from tables according to their tags. Wildcard tags can be specified in both storage and retrieval.
To use the message manager, you must include
link with the Converse library.
In actuality, the term ``message manager'' is unnecessarily specific. The message manager can store and retrieve arbitrary pointers according to a set of tags. The pointers do not necessarily need to be pointers to Converse messages. They can be pointers to anything.
typedef struct CmmTableStruct *CmmTable
This opaque type is defined in
converse.h. It represents
a table which can be used to store messages. No information is publicized
about the format of a CmmTableStruct.
void CmmPut(CmmTable t, int ntags, int *tags, void *msg)
This function inserts a message into a message table, along with an array of tags.
ntags specifies the length of the
tags array contains the tags themselves.
t specify the message and table, respectively.
void *CmmGet(CmmTable t, int ntags, int *tags, int *ret_tags)
This function looks up a message from a message table. A message will be retrieved that ``matches'' the specified
array. If a message is found that ``matches'', the tags with which
it was stored are copied into the
ret_tags array, a pointer
to the message will be returned, and the message will be deleted
from the table. If no match is found, 0 will be returned.
To ``match'', the array
tags must be of the same length as the
stored array. Similarly, all the individual tags in the stored array
must ``match'' the tags in the
tags array. Two tags match if they
are equal to each other, or if
either tag is equal to
CmmWildCard (this means one can
store messages with
wildcard tags, making it easier to find those messages on retrieval).
void CmmFree(CmmTable t);
This function frees a message-table t. WARNING: It also frees all the messages that have been inserted into the message table. It assumes that the correct way to do this is to call
CmiFree on the message.
If this assumption is incorrect, a crash will occur. The way to avoid
this problem is to remove and properly dispose all the messages in a table
before disposing the table itself.