diff options
author | Casey Corn <cmccad@yahoo.com> | 2003-05-27 02:53:16 +0400 |
---|---|---|
committer | Casey Corn <cmccad@yahoo.com> | 2003-05-27 02:53:16 +0400 |
commit | a0e54446f3ac1ba6adf87cd01d4d7b63fbbf538b (patch) | |
tree | b8c10b19515acaf0e91a7a6da33db5acbd8de143 /source/blender/src/mainqueue.c | |
parent | f88284664149e114272aeea3e1deb5c0e105c674 (diff) |
Added cgul's comments.
Diffstat (limited to 'source/blender/src/mainqueue.c')
-rw-r--r-- | source/blender/src/mainqueue.c | 87 |
1 files changed, 84 insertions, 3 deletions
diff --git a/source/blender/src/mainqueue.c b/source/blender/src/mainqueue.c index a4b4e21babd..697eef1322a 100644 --- a/source/blender/src/mainqueue.c +++ b/source/blender/src/mainqueue.c @@ -1,4 +1,4 @@ -/** +/* * $Id$ * * ***** BEGIN GPL/BL DUAL LICENSE BLOCK ***** @@ -28,9 +28,24 @@ * Contributor(s): none yet. * * ***** END GPL/BL DUAL LICENSE BLOCK ***** + */ + +/** + * \file mainqueue.c + * \brief Just the functions to maintain a central event queue. * - * Just the functions to maintain a central event - * queue. + * Creates the functionality of a FIFO queue for events. + * + * \note The documentor (me) doesn't know the full description of + * the fields of the QEvent structure, and the parameters to the + * functions (event, val, ascii). The comments should be updated + * with more detailed descriptions of what is stored in each one. + * + * \warning This queue structure uses a method that assumes the presence + * of allocated memory. As well it doesn't de-allocate memory after + * a read off of the queue, thereby causing a situation whereby memory + * isn't being freed and can grow with out bound even though there is + * a limit on the queue size. */ #include <stdlib.h> @@ -41,15 +56,49 @@ #include <config.h> #endif +/** + * \struct QEvent + * \brief This is the definition for the event queue datastructure + */ typedef struct { + /** + * \var unsigned short event + * \brief holds the event type + */ unsigned short event; + /** + * \var short val + */ short val; + /** + * \var char ascii + */ char ascii; } QEvent; +/** + * \var static QEvent mainqueue[MAXQUEUE] + * \brief The Main Queue store. + */ static QEvent mainqueue[MAXQUEUE]; + +/** + * \var static unsigned int nevents=0 + * \brief The count of the events currently stored. + */ static unsigned int nevents= 0; +/** + * \brief Reads and removes events from the queue and returns the event type, + * if the queue is empty return 0. + * \param val the val of the event to read into. + * \param ascii the buffer of the event to read into. + * \return the event type or 0 if no event. + * + * Pops off the last item in the queue and returns the pieces in their + * little parts. The last item was the oldest item in the queue. + * + */ unsigned short mainqread(short *val, char *ascii) { if (nevents) { @@ -62,11 +111,24 @@ unsigned short mainqread(short *val, char *ascii) return 0; } +/** + * \brief A short cut to mainqenter_ext setting ascii to 0 + */ void mainqenter(unsigned short event, short val) { mainqenter_ext(event, val, 0); } +/** + * \brief Adds event to the beginning of the queue. + * \param event the event type. + * \param val the val of the event. + * \param ascii the event characters. + * + * If the event isn't nothing, and if the queue still + * has some room, then add to the queue. Otherwise the + * event is lost. + */ void mainqenter_ext(unsigned short event, short val, char ascii) { if (!event) @@ -83,6 +145,19 @@ void mainqenter_ext(unsigned short event, short val, char ascii) } } +/** + * \brief Pushes and event back on to the front of the queue. + * \param event + * \param val + * \param ascii + * + * Pushes an event back onto the queue, possibly after a peek + * at the item. This method assumes that the memory has already + * been allocated and should be mentioned in a precondition. + * + * \pre This method assumes that the memory is already allocated + * for the event. + */ void mainqpushback(unsigned short event, short val, char ascii) { if (nevents<MAXQUEUE) { @@ -93,6 +168,12 @@ void mainqpushback(unsigned short event, short val, char ascii) } } +/** + * \brief Returns the event type from the last item in the queue + * (the next one that would be popped off). Probably used as a test + * to see if the queue is empty or if a valid event is still around. + * \return the event type of the last item in the queue + */ unsigned short mainqtest() { if (nevents) |