]>
Commit | Line | Data |
---|---|---|
189935b1 | 1 | Many messages generated by an IRC server are sent to multiple |
2 | recipients. Previous versions of ircd used DBuf to store these | |
3 | messages until they could actually be sent. The problem with using a | |
4 | DBuf for this, though, is that there are multiple copies of the same | |
5 | message hanging around. Another problem is that there is at least one | |
6 | strcpy() or equivalent call for each destination the message is sent | |
7 | to. A simple solution to this problem is to use messages queues. | |
8 | This file documents the MsgQ interface for ircd. | |
9 | ||
10 | The MsgQ interface is loosely based on the API for DBuf. Although the | |
11 | structures are vastly different, most calls, including several of the | |
12 | macros, are similar to certain pieces of the DBuf API. This made | |
13 | retrofitting ircd with MsgQ support much simpler. | |
14 | ||
15 | <struct> | |
16 | struct MsgCounts { | |
17 | int alloc; | |
18 | int used; | |
19 | }; | |
20 | ||
21 | The MsgCounts structure may be used for determining how much memory is | |
22 | in use by the MsgQ system. The _alloc_ element is a count of the | |
23 | total number of structures (of whatever type) that have been | |
24 | allocated; the _used_ element is a count of how many are actually in | |
25 | use. MsgQ never releases any of its allocated memory; instead, it | |
26 | places unused structures onto a free list. | |
27 | </struct> | |
28 | ||
29 | <struct> | |
30 | struct MsgBuf; | |
31 | ||
32 | The MsgBuf structure contains the actual message, along with a | |
33 | reference count and the message's length. None of its fields are | |
34 | directly accessible by the application. | |
35 | </struct> | |
36 | ||
37 | <struct> | |
38 | struct MsgQ; | |
39 | ||
40 | The MsgQ structure is a structure allocated by the application that is | |
41 | used by the MsgQ system to describe an entire message queue, including | |
42 | both normal and priority queues. None of its fields are directly | |
43 | accessible by the application. | |
44 | </struct> | |
45 | ||
46 | <global> | |
47 | struct MsgCounts msgBufCounts; /* resource count for struct MsgBuf */ | |
48 | ||
49 | This global variable counts the number of MsgBuf structures that have | |
50 | been allocated. This may be used to determine how much memory is in | |
51 | use by the MsgQ system. | |
52 | </global> | |
53 | ||
54 | <global> | |
55 | struct MsgCounts msgCounts; /* resource count for struct Msg */ | |
56 | ||
57 | This global variable counts the number of Msg structures that have | |
58 | been allocated. The Msg structure describes the link between a queue | |
59 | and a message. It is not accessible to the application, and so not | |
60 | further documented here. | |
61 | </global> | |
62 | ||
63 | <function> | |
64 | unsigned int MsgQLength(struct MsgQ* mq); | |
65 | ||
66 | This macro returns the number of bytes in a particular user's message | |
67 | queue. | |
68 | </function> | |
69 | ||
70 | <function> | |
71 | unsigned int MsgQCount(struct MsgQ* mq); | |
72 | ||
73 | This macro returns the number of messages in a particular user's | |
74 | message queue. | |
75 | </function> | |
76 | ||
77 | <function> | |
78 | void MsgQClear(struct MsgQ* mq); | |
79 | ||
80 | This macro simply clears the content of a particular message queue. | |
81 | NOTE: This macro evaluates its argument twice. | |
82 | </function> | |
83 | ||
84 | <function> | |
85 | void msgq_init(struct MsgQ *mq); | |
86 | ||
87 | This function initializes a caller-allocated message queue to be | |
88 | empty. Calling this function on a message queue with messages in it | |
89 | WILL RESULT IN A MEMORY LEAK. | |
90 | </function> | |
91 | ||
92 | <function> | |
93 | void msgq_delete(struct MsgQ *mq, unsigned int length); | |
94 | ||
95 | This function removes the given number of bytes from the message | |
96 | queue. If entire messages have been sent, they will be unlinked from | |
97 | the queue. The _length_ parameter does not need to correspond to a | |
98 | given message's length; the MsgQ system is able to deal with messages | |
99 | that have only partially been sent. | |
100 | </function> | |
101 | ||
102 | <function> | |
103 | int msgq_mapiov(const struct MsgQ *mq, struct iovec *iov, int count, | |
104 | unsigned int *len); | |
105 | ||
106 | The msgq_mapiov() function takes a struct MsgQ (specified by the _mq_ | |
107 | parameter) and a caller allocated struct iovec array (specified by the | |
108 | _iov_ parameter) and maps the contents of the message into the struct | |
109 | iovec array. The _count_ parameter must indicate the total number of | |
110 | elements available for msgq_mapiov() to use. The _len_ parameter must | |
111 | be a pointer to an unsigned int, and upon return from the function | |
112 | will contain the total number of bytes that have been mapped into the | |
113 | struct iovec array. This function returns the number of struct iovec | |
114 | elements that have been filled. For more information about the | |
115 | purpose of struct iovec, see your system's man page for the writev() | |
116 | function. | |
117 | </function> | |
118 | ||
119 | <function> | |
120 | struct MsgBuf *msgq_make(struct Client *dest, const char *format, ...); | |
121 | ||
122 | This function allocates a struct MsgBuf and calls ircd_vsnprintf() | |
123 | with the _dest_ and _format_ parameters to fill it in. Most callers | |
124 | should use the send_buffer() function (declared in send.h) to attach | |
125 | the struct MsgBuf to a client's message queue. | |
126 | </function> | |
127 | ||
128 | <function> | |
129 | struct MsgBuf *msgq_vmake(struct Client *dest, const char *format, va_list vl); | |
130 | ||
131 | This function is identical to msgq_make() except that it takes a | |
132 | va_list (given by the _vl_ parameter) and calls ircd_vsnprintf() to | |
133 | format the message. | |
134 | </function> | |
135 | ||
136 | <function> | |
137 | void msgq_append(struct Client *dest, struct MsgBuf *mb, const char *format, | |
138 | ...); | |
139 | ||
140 | Occasionally a caller is not able to completely compute a message | |
141 | before calling msgq_make(). When this happens, the msgq_append() | |
142 | function may be called to append more text onto the struct MsgBuf | |
143 | specified by the _mb_ parameter. As with msgq_make(), the _dest_ and | |
144 | _format_ parameters are passed to ircd_vsnprintf(), along with the | |
145 | additional arguments. | |
146 | </function> | |
147 | ||
148 | <function> | |
149 | void msgq_clean(struct MsgBuf *mb); | |
150 | ||
151 | As mentioned above, struct MsgBuf includes a reference count. When | |
152 | that reference count reaches zero, the structure is released. The | |
153 | reference count is set to 1 by msgq_make() and msgq_vmake(). Once a | |
154 | given message has been attached to all the queues it needs to be, the | |
155 | caller should call the msgq_clean() function to decrement this | |
156 | reference count. This function will place the struct MsgBuf back onto | |
157 | the free list if it did not get attached to any message queues. The | |
158 | msgq_delete() function calls msgq_clean() internally, so the | |
159 | application need not call msgq_clean() explicitly afterwards. | |
160 | </function> | |
161 | ||
162 | <function> | |
163 | void msgq_add(struct MsgQ *mq, struct MsgBuf *mb, int prio); | |
164 | ||
165 | This function is used to attach a given struct MsgBuf, as specified by | |
166 | the _mb_ parameter, to a given message queue. The _prio_ parameter, | |
167 | if non-zero, specifies that the message should be placed on the | |
168 | priority queue. This function is called by send_buffer(), defined in | |
169 | send.h; most applications should call that function, rather than this | |
170 | one. | |
171 | </function> | |
172 | ||
173 | <function> | |
174 | void msgq_count_memory(size_t *msg_alloc, size_t *msg_used, | |
175 | size_t *msgbuf_alloc, size_t *msgbuf_used); | |
176 | ||
177 | This function simply takes the counts kept in msgBufCounts and | |
178 | msgCounts and multiplies them by the appropriate structure sizes, | |
179 | storing the resulting sizes into its parameters. | |
180 | </function> | |
181 | ||
182 | <function> | |
183 | unsigned int msgq_bufleft(struct MsgBuf *mb); | |
184 | ||
185 | This function is for use in conjunction with msgq_append(). It | |
186 | returns the total number of bytes of free storage in the given _mb_. | |
187 | </function> | |
188 | ||
189 | <authors> | |
190 | Kev <klmitch@mit.edu> | |
191 | </authors> | |
192 | ||
193 | <changelog> | |
194 | [2001-6-15 Kev] Initial documentation for the MsgQ functions. | |
195 | </changelog> |