sync undernet upstream ircu changes.

[irc/quakenet/snircd.git] / doc / api / msgq.txt

Many messages generated by an IRC server are sent to multiple
recipients.  Previous versions of ircd used DBuf to store these
messages until they could actually be sent.  The problem with using a
DBuf for this, though, is that there are multiple copies of the same
message hanging around.  Another problem is that there is at least one
strcpy() or equivalent call for each destination the message is sent
to.  A simple solution to this problem is to use messages queues.
This file documents the MsgQ interface for ircd.

The MsgQ interface is loosely based on the API for DBuf.  Although the
structures are vastly different, most calls, including several of the
macros, are similar to certain pieces of the DBuf API.  This made
retrofitting ircd with MsgQ support much simpler.

<struct>
struct MsgCounts {
  int alloc;
  int used;
};

The MsgCounts structure may be used for determining how much memory is
in use by the MsgQ system.  The _alloc_ element is a count of the
total number of structures (of whatever type) that have been
allocated; the _used_ element is a count of how many are actually in
use.  MsgQ never releases any of its allocated memory; instead, it
places unused structures onto a free list.
</struct>

<struct>
struct MsgBuf;

The MsgBuf structure contains the actual message, along with a
reference count and the message's length.  None of its fields are
directly accessible by the application.
</struct>

<struct>
struct MsgQ;

The MsgQ structure is a structure allocated by the application that is
used by the MsgQ system to describe an entire message queue, including
both normal and priority queues.  None of its fields are directly
accessible by the application.
</struct>

<global>
struct MsgCounts msgBufCounts;	/* resource count for struct MsgBuf */

This global variable counts the number of MsgBuf structures that have
been allocated.  This may be used to determine how much memory is in
use by the MsgQ system.
</global>

<global>
struct MsgCounts msgCounts;	/* resource count for struct Msg */

This global variable counts the number of Msg structures that have
been allocated.  The Msg structure describes the link between a queue
and a message.  It is not accessible to the application, and so not
further documented here.
</global>

<function>
unsigned int MsgQLength(struct MsgQ* mq);

This macro returns the number of bytes in a particular user's message
queue.
</function>

<function>
unsigned int MsgQCount(struct MsgQ* mq);

This macro returns the number of messages in a particular user's
message queue.
</function>

<function>
void MsgQClear(struct MsgQ* mq);

This macro simply clears the content of a particular message queue.
NOTE: This macro evaluates its argument twice.
</function>

<function>
void msgq_init(struct MsgQ *mq);

This function initializes a caller-allocated message queue to be
empty.  Calling this function on a message queue with messages in it
WILL RESULT IN A MEMORY LEAK.
</function>

<function>
void msgq_delete(struct MsgQ *mq, unsigned int length);

This function removes the given number of bytes from the message
queue.  If entire messages have been sent, they will be unlinked from
the queue.  The _length_ parameter does not need to correspond to a
given message's length; the MsgQ system is able to deal with messages
that have only partially been sent.
</function>

<function>
int msgq_mapiov(const struct MsgQ *mq, struct iovec *iov, int count,
		unsigned int *len);

The msgq_mapiov() function takes a struct MsgQ (specified by the _mq_
parameter) and a caller allocated struct iovec array (specified by the
_iov_ parameter) and maps the contents of the message into the struct
iovec array.  The _count_ parameter must indicate the total number of
elements available for msgq_mapiov() to use.  The _len_ parameter must
be a pointer to an unsigned int, and upon return from the function
will contain the total number of bytes that have been mapped into the
struct iovec array.  This function returns the number of struct iovec
elements that have been filled.  For more information about the
purpose of struct iovec, see your system's man page for the writev()
function.
</function>

<function>
struct MsgBuf *msgq_make(struct Client *dest, const char *format, ...);

This function allocates a struct MsgBuf and calls ircd_vsnprintf()
with the _dest_ and _format_ parameters to fill it in.  Most callers
should use the send_buffer() function (declared in send.h) to attach
the struct MsgBuf to a client's message queue.
</function>

<function>
struct MsgBuf *msgq_vmake(struct Client *dest, const char *format, va_list vl);

This function is identical to msgq_make() except that it takes a
va_list (given by the _vl_ parameter) and calls ircd_vsnprintf() to
format the message.
</function>

<function>
void msgq_append(struct Client *dest, struct MsgBuf *mb, const char *format,
		 ...);

Occasionally a caller is not able to completely compute a message
before calling msgq_make().  When this happens, the msgq_append()
function may be called to append more text onto the struct MsgBuf
specified by the _mb_ parameter.  As with msgq_make(), the _dest_ and
_format_ parameters are passed to ircd_vsnprintf(), along with the
additional arguments.
</function>

<function>
void msgq_clean(struct MsgBuf *mb);

As mentioned above, struct MsgBuf includes a reference count.  When
that reference count reaches zero, the structure is released.  The
reference count is set to 1 by msgq_make() and msgq_vmake().  Once a
given message has been attached to all the queues it needs to be, the
caller should call the msgq_clean() function to decrement this
reference count.  This function will place the struct MsgBuf back onto
the free list if it did not get attached to any message queues.  The
msgq_delete() function calls msgq_clean() internally, so the
application need not call msgq_clean() explicitly afterwards.
</function>

<function>
void msgq_add(struct MsgQ *mq, struct MsgBuf *mb, int prio);

This function is used to attach a given struct MsgBuf, as specified by
the _mb_ parameter, to a given message queue.  The _prio_ parameter,
if non-zero, specifies that the message should be placed on the
priority queue.  This function is called by send_buffer(), defined in
send.h; most applications should call that function, rather than this
one.
</function>

<function>
void msgq_count_memory(size_t *msg_alloc, size_t *msg_used,
		       size_t *msgbuf_alloc, size_t *msgbuf_used);

This function simply takes the counts kept in msgBufCounts and
msgCounts and multiplies them by the appropriate structure sizes,
storing the resulting sizes into its parameters.
</function>

<function>
unsigned int msgq_bufleft(struct MsgBuf *mb);

This function is for use in conjunction with msgq_append().  It
returns the total number of bytes of free storage in the given _mb_.
</function>

<authors>
Kev <klmitch@mit.edu>
</authors>

<changelog>
[2001-6-15 Kev] Initial documentation for the MsgQ functions.
</changelog>