Add more docs to the thread_queue

src/ucore_threadqueue.h

@@ -47,34 +47,26 @@ extern "C" {
  */
  
 /**
- * A thread message.
+ * A thread message used to add and retrieve messages
- *
+ * from in a queue.
- * @ingroup ThreadQueue
+ * An application must not touch this struct 
- *
+ * when a message is present (i.e. it has been added
- * This is used for passing to #thread_queue_get for retreive messages.
+ * to a queue, but not retrieved yet) in a queue.
- * the date is stored in the data member, the message type in the  #msgtype.
- * 
- * Typical:
- * @code
- * struct threadmsg;
- * struct myfoo *foo;
- * while(1)
- * 	ret = thread_queue_get(&queue,NULL,&message);
- * 	..
- * 	foo = msg.data;
- * 	switch(msg.msgtype){
- * 		...
- * 	}
- * }
- * @endcode
  *
  */
 struct uc_threadmsg{
 	/**
-	 * Holds the messagetype
+	 * A message type the application can use to 
+     * discriminate different messages.
+     * A negative value will cause a uc_threadmsg to
+     * be added to the head of a queue.
 	 */
 	long msgtype;
 
+    /**
+     * Internal pointer used by the uc_thread_queue.
+     * Applications must not use this member.
+     */
     struct uc_threadmsg *next;
 };
 
@@ -84,12 +76,53 @@ struct uc_threadmsg{
  * 
  * @ingroup ThreadQueue
  * 
- * You should threat this struct as opaque, never ever set/get any
+ * You should threat this struct as opaque never ever access any of 
- * of the variables. You have been warned.
+ * the variables in this struct.
+ * You have been warned.
+ *
+ * The uc_thread_queue_ functions only deal with struct uc_threadmsg
+ * structs.
+ * In order for the message passing to be useful, more data needs to be
+ * associated with a message, it's up to the application to manage this.
+ * One way is to e.g. add the struct uc_threadmsg as the first member
+ * of a larger struct, and recover the larger struct after getting a 
+ * struct uc_threadmsg out of the queue. e.g.
+ *
+ * @code
+ * struct my_msg {
+ *   struct uc_threadmsg tmsg;
+ *   int foo;
+ *   char bar[32];
+ * };
+ *
+ * struct my_msg *msg = malloc(sizeof *msg);
+ * msg->tmsg.msgtype = MSGTYP1;
+ * ...
+ * uc_thread_queue_add(queue, &msg->tmsg);
+ *
+ * The receiver end does e.g.
+ *
+ * struct uc_threadmsg *tmsg;
+ * uc_thread_queue_get(queue, NULL, &tmsg);
+ * switch(tmsg->msgtype) {
+ *   case MYMSG1; {
+ *      struct my_msg *msg = (struct my_msg*)tmsg;
+ *      ...
+ *      free(msg);
+ *      break
+ *   ...
+ *   }
+ * }
+ *
+ * @endcode
+ *
+ *
+ *
+ *
  */
 struct uc_threadqueue {
 /**
- * Number of elements in the queue, never set this, never read this.
+ * Number of elements in the queue.
  * Use #threadqueue_length to read it.
  */
 	long num_elements;
@@ -97,15 +130,15 @@ struct uc_threadqueue {
 /** Max number of elements this queue will hold */
     long max_elements;
 /**
- * Mutex for the queue, never touch.
+ * Mutex for the queue.
  */
 	pthread_mutex_t mutex;
 /**
- * Condition variable for readers on the queue, never touch.
+ * Condition variable for readers on the queue.
  */
 	pthread_cond_t read_cond;
 /**
- * Condition variable for writers on the queue (if the queue is full) never touch.
+ * Condition variable for writers on the queue (if the queue is full).
  */
 	pthread_cond_t write_cond;
 /** 
@@ -118,7 +151,7 @@ struct uc_threadqueue {
     long num_write_waiters;
 
 /**
- * Internal pointers for the queue, never touch.
+ * Internal pointers for the messages in the queue.
  */
 	struct uc_threadmsg *first,**last;
 };
@@ -130,11 +163,15 @@ struct uc_threadqueue {
  * 
  * thread_queue_init initializes a new threadqueue. A new queue must always
  * be initialized before it is used.
+ * A max number of elements the queue will hold must be given.
+ * Adding more elements than a queue will hold will e.g. cause
+ * uc_thread_queue_add to block until space becomes available.
  *
  * @param queue Pointer to the queue that should be initialized
  * @param max_elements Max number of elements this queue can hold.
  *
- * @return 0 on success see pthread_mutex_init
+ * @return 0 on success EINVAL if queue is NULL or max_elements <= 0, or
+ * another errno value if pthread_ functions fails
  */
 int uc_thread_queue_init(struct uc_threadqueue *queue, long max_elements);
 
@@ -143,16 +180,24 @@ int uc_thread_queue_init(struct uc_threadqueue *queue, long max_elements);
  *
  * @ingroup ThreadQueue
  * 
- * thread_queue_add adds a "message" to the specified queue, a message
+ * thread_queue_add adds a "message" to the specified queue. 
- * is just a pointer to a anything of the users choice. Nothing is copied
+ * It is up to the application to manage the data and memory indicated by the
- * so the user must keep track on (de)allocation of the data.
+ * struct uc_threadmsg. 
- * A message type is also specified, it is not used for anything else than
+ * The struct uc_threadmsg is assumed to be an intrusive pointer,
- * given back when a message is retreived from the queue.
+ * e.g. it can be the first member of a larger struct actually containing the
+ * data to be passed over.
+ *
+ * Nothing is copied so the application must keep track on (de)allocation of the pointers.
+ * A message type can also be also specified, to e.g. help discriminate
+ * messages when messages are received.
+ *
+ * If the message_type member of @msg is negative, the message is added to
+ * the front of the queue, i.e. it can be considered a "priority" message.
  *
  * @param queue Pointer to the queue on where the message should be added.
  * @param data the "message".
- * @param msgtype a long specifying the message type, choice of the user.
+ * @return 0 on succes ENOMEM if out of memory EINVAL if queue is NULL, or other
- * @return 0 on succes ENOMEM if out of memory EINVAL if queue is NULL
+ * errno values if pthread functions failed.
  */
 int uc_thread_queue_add(struct uc_threadqueue *queue, struct uc_threadmsg *msg);
 
@@ -162,7 +207,7 @@ int uc_thread_queue_add(struct uc_threadqueue *queue, struct uc_threadmsg *msg);
  * @ingroup ThreadQueue
  *
  * thread_queue_get gets a message from the specified queue, it will block
- * the caling thread untill a message arrives, or the (optional) timeout occurs.
+ * the caøling thread untill a message arrives, or the (optional) timeout occurs.
  * If timeout is NULL, there will be no timeout, and thread_queue_get will wait
  * untill a message arrives.
  *
@@ -197,11 +242,11 @@ long uc_thread_queue_length( struct uc_threadqueue *queue );
 
 /**
  * @ingroup ThreadQueue
- * Cleans up the queue.
+ * Destroy a queue.
  * 
- * threadqueue_cleanup cleans up and destroys the queue.
+ * Destroy the queue.
- * This will remove all messages from a queue, and reset it. If
+ *
- * freedata is != 0 free(3) will be called on all pending messages in the queue
+ * If freedata is != 0 free(3) will be called on all pending messages in the queue
  * You cannot call this if there are someone currently adding or getting messages
  * from the queue.
  * After a queue have been cleaned, it cannot be used again untill #thread_queue_init
@@ -212,7 +257,7 @@ long uc_thread_queue_length( struct uc_threadqueue *queue );
  * messages
  * @return 0 on success EINVAL if queue is NULL EBUSY if someone is holding any locks on the queue
  */
-int uc_thread_queue_cleanup(struct uc_threadqueue *queue, int freedata);
+int uc_thread_queue_destroy(struct uc_threadqueue *queue, int freedata);
 
 #ifdef __cplusplus
 }