\chapter{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 {\tt 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 {\em not} necessarily
need to be pointers to \converse{} messages.  They can be pointers to
anything.

\function{typedef struct CmmTableStruct *CmmTable}
\index{CmmTable}
\desc{This opaque type is defined in {\tt converse.h}.  It represents
a table which can be used to store messages.  No information is publicized
about the format of a CmmTableStruct.}

\function{\#define CmmWildCard (-1)}
\index{CmmWildCard}
\desc{This \#define is in {\tt converse.h}.  The tag -1 is the ``wild
card'' for the tag-based lookup functions in the message manager.}

\function{CmmTable CmmNew();}
\index{CmmNew}
\desc{This function creates a new message-table and returns it.}

\function{void CmmPut(CmmTable t, int ntags, int *tags, void *msg)}
\desc{This function inserts a message into a message table, along with
an array of tags.  {\tt ntags} specifies the length of the {\tt tags}
array.  The {\tt tags} array contains the tags themselves.  {\tt msg}
and {\tt t} specify the message and table, respectively.}

\function{void *CmmGet(CmmTable t, int ntags, int *tags, int *ret\_tags)}
\index{CmmGet}
\desc{This function looks up a message from a message table.  A
message will be retrieved that ``matches'' the specified {\tt tags}
array.  If a message is found that ``matches'', the tags with which
it was stored are copied into the {\tt 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 {\tt 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 {\tt tags} array.  Two tags match if they
are equal to each other, or if {\tt either} tag is equal to {\tt
CmmWildCard} (this means one can {\tt store} messages with
wildcard tags, making it easier to find those messages on retrieval).}

\function{void *CmmProbe(CmmTable t, int ntags, int *tags, int *ret\_tags)}
\index{CmmProbe}
\desc{This function is identical to {\tt CmmGet} above, except that
the message is not deleted from the table.}

\function{void CmmFree(CmmTable t);}
\index{CmmFree}
\desc{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 {\tt 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.}


