X-Git-Url: http://git.pk910.de/?p=ircu2.10.12-pk.git;a=blobdiff_plain;f=doc%2Fapi%2Fmsgq.txt;fp=doc%2Fapi%2Fmsgq.txt;h=cfa6ef6545a8288d3d5ca9313205028b81f2246e;hp=0000000000000000000000000000000000000000;hb=0400a5a6479398d82526785c18c0df8bc8b92dce;hpb=d17e10da972ce5776c60b4c317267c6abe0e1ead

diff --git a/doc/api/msgq.txt b/doc/api/msgq.txt
new file mode 100644
index 0000000..cfa6ef6
--- /dev/null
+++ b/doc/api/msgq.txt
@@ -0,0 +1,195 @@
+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>