doc/api/msgq.txt

   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>