*** empty log message ***
[charm.git] / doc / converse / msgmgr.tex
1 \chapter{Tag Matching and the Message Manager}
2
3 The message manager is a data structure that can be used to put together
4 runtime systems for languages that support tag-based message
5 retrieval.
6
7 The purpose of the message manager is to store, index, and retrieve
8 messages according to a set of integer tags.  It provides functions to
9 create tables, functions to insert messages into tables (specifying
10 their tags), and functions to selectively retrieve messages from
11 tables according to their tags.  Wildcard tags can be specified in
12 both storage and retrieval.
13
14
15 To use the message manager, you must include {\tt converse.h} and
16 link with the converse library.
17
18 In actuality, the term ``message manager'' is unnecessarily specific.
19 The message manager can store and retrieve arbitrary pointers
20 according to a set of tags.  The pointers do {\em not} necessarily
21 need to be pointers to converse messages.  They can be pointers to
22 anything.
23
24 \function{typedef struct CmmTableStruct *CmmTable}
25 \index{CmmTable}
26 \desc{This opaque type is defined in {\tt converse.h}.  It represents
27 a table which can be used to store messages.  No information is publicized
28 about the format of a CmmTableStruct.}
29
30 \function{\#define CmmWildCard (-1)}
31 \index{CmmWildCard}
32 \desc{This \#define is in {\tt converse.h}.  The tag -1 is the ``wild
33 card'' for the tag-based lookup functions in the message manager.}
34
35 \function{CmmTable CmmNew();}
36 \index{CmmNew}
37 \desc{This function creates a new message-table and returns it.}
38
39 \function{void CmmPut(CmmTable t, int ntags, int *tags, void *msg)}
40 \desc{This function inserts a message into a message table, along with
41 an array of tags.  {\tt ntags} specifies the length of the {\tt tags}
42 array.  The {\tt tags} array contains the tags themselves.  {\tt msg}
43 and {\tt t} specify the message and table, respectively.}
44
45 \function{void *CmmGet(CmmTable t, int ntags, int *tags, int *ret\_tags)}
46 \index{CmmGet}
47 \desc{This function looks up a message from a message table.  A
48 message will be retrieved that ``matches'' the specified {\tt tags}
49 array.  If a message is found that ``matches'', the tags with which
50 it was stored are copied into the {\tt ret\_tags} array, a pointer
51 to the message will be returned, and the message will be deleted
52 from the table.  If no match is found, 0 will be returned.
53
54 To ``match'', the array {\tt tags} must be of the same length as the
55 stored array.  Similarly, all the individual tags in the stored array
56 must ``match'' the tags in the {\tt tags} array.  Two tags match if they
57 are equal to each other, or if {\tt either} tag is equal to {\tt
58 CmmWildCard} (this means one can {\tt store} messages with
59 wildcard tags, making it easier to find those messages on retrieval).}
60
61 \function{void *CmmProbe(CmmTable t, int ntags, int *tags, int *ret\_tags)}
62 \index{CmmProbe}
63 \desc{This function is identical to {\tt CmmGet} above, except that
64 the message is not deleted from the table.}
65
66 \function{void CmmFree(CmmTable t);}
67 \index{CmmFree}
68 \desc{This function frees a message-table t.  WARNING: It also frees all
69 the messages that have been inserted into the message table.  It assumes
70 that the correct way to do this is to call {\tt CmiFree} on the message.
71 If this assumption is incorrect, a crash will occur.  The way to avoid
72 this problem is to remove and properly dispose all the messages in a table
73 before disposing the table itself.}
74
75