2. Tag Matching

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 converse.h and 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.

#define CmmWildCard (-1)
This #define is in converse.h. The tag -1 is the ``wild card'' for the tag-based lookup functions in the message manager.

CmmTable CmmNew();
This function creates a new message-table and returns it.

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. The tags array contains the tags themselves. msg and 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 tags 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 *CmmProbe(CmmTable t, int ntags, int *tags, int *ret_tags)
This function is identical to CmmGet above, except that the message is not deleted from the table.

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.