From 0afea336ef812f75d21e9c9c74cd4673f2b564f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nils=20O=2E=20Sel=C3=A5sdal?= Date: Wed, 14 Nov 2012 19:23:05 +0100 Subject: [PATCH] More threadqueue docs & tests --- src/ucore_threadqueue.h | 52 +++++++---------------------------------- test/test_threadqueue.c | 50 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 59 insertions(+), 43 deletions(-) diff --git a/src/ucore_threadqueue.h b/src/ucore_threadqueue.h index ff14253..a6cfe4c 100644 --- a/src/ucore_threadqueue.h +++ b/src/ucore_threadqueue.h @@ -8,43 +8,14 @@ extern "C" { #endif /** * @defgroup ThreadQueue ThreadQueue + * @{ * * Little API for waitable queues, typically used for passing messages * between threads. * - * @author Nils O. Selåsdal + * @author Nils O. SelÃ¥sdal */ -/** - * @mainpage - * @htmlonly - * 
- *  Copyright (c) 2002-2003 Nils O. Selåsdal .
- *  All rights reserved, all wrongs reversed.
- *  
- *  Redistribution and use in source and binary forms, with or without
- *  modification, are permitted provided that the following conditions
- *  are met:
- *
- *  1. Redistributions of source code must retain the above copyright
- *     notice, this list of conditions and the following disclaimer.
- *  2. Redistributions in binary form must reproduce the above copyright
- *     notice, this list of conditions and the following disclaimer in the
- *     documentation and/or other materials provided with the distribution.
- *
- *  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
- *  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- *  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
- *  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
- *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
- *  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
- *  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * @endhtmlonly - */ /** * A thread message used to add and retrieve messages @@ -70,13 +41,15 @@ struct uc_threadmsg{ struct uc_threadmsg *next; }; +/** + * Callback function for the walk and destroy functions. + */ typedef void (*uc_thread_queue_walk_func) (struct uc_threadmsg *msg); /** * A ThreadQueue * - * @ingroup ThreadQueue * * You should threat this struct as opaque never ever access any of * the variables in this struct. @@ -161,8 +134,6 @@ struct uc_threadqueue { /** * Initializes a queue. * - * @ingroup 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. @@ -180,8 +151,6 @@ int uc_thread_queue_init(struct uc_threadqueue *queue, long max_elements); /** * Adds a message to a queue * - * @ingroup ThreadQueue - * * thread_queue_add adds a "message" to the specified queue. * It is up to the application to manage the data and memory indicated by the * struct uc_threadmsg. @@ -206,10 +175,8 @@ int uc_thread_queue_add(struct uc_threadqueue *queue, struct uc_threadmsg *msg); /** * Gets a message from a queue * - * @ingroup ThreadQueue - * * thread_queue_get gets a message from the specified queue, it will block - * the caøling thread untill a message arrives, or the (optional) timeout occurs. + * the caling 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. * @@ -233,8 +200,6 @@ int uc_thread_queue_get(struct uc_threadqueue *queue, const struct timespec *tim /** * Gets the length of a queue * - * @ingroup ThreadQueue - * * threadqueue_length returns the number of messages waiting in the queue * * @param queue Pointer to the queue for which to get the length @@ -243,7 +208,6 @@ int uc_thread_queue_get(struct uc_threadqueue *queue, const struct timespec *tim long uc_thread_queue_length( struct uc_threadqueue *queue ); /** - * @ingroup ThreadQueue * Destroy the queue. * * If free_func is != NULL, free_func will be called for every item, allowing you to free @@ -261,7 +225,6 @@ long uc_thread_queue_length( struct uc_threadqueue *queue ); int uc_thread_queue_destroy(struct uc_threadqueue *queue, uc_thread_queue_walk_func free_func); /** - * @ingroup ThreadQueue * Walk the elements of the queue, intended for debugging * * The supplied function will be called for each item in the queue, internal queue @@ -275,6 +238,9 @@ int uc_thread_queue_destroy(struct uc_threadqueue *queue, uc_thread_queue_walk_f */ int uc_thread_queue_walk(struct uc_threadqueue *queue, uc_thread_queue_walk_func walk_func); +/** + * @}*/ + #ifdef __cplusplus } #endif diff --git a/test/test_threadqueue.c b/test/test_threadqueue.c index 108da57..31512aa 100644 --- a/test/test_threadqueue.c +++ b/test/test_threadqueue.c @@ -1,5 +1,6 @@ #include #include +#include #include #include #include "ucore_threadqueue.h" @@ -198,6 +199,53 @@ START_TEST (test_thread_queue_multiple_writers) END_TEST +START_TEST (test_thread_queue_timeout1) + + struct uc_threadqueue queue; + struct timespec timeout = {0, 1000}; + struct uc_threadmsg *msg; + + fail_if(uc_thread_queue_init(&queue, 100) != 0); + + fail_if(uc_thread_queue_get(&queue, &timeout, &msg) != ETIMEDOUT); + uc_thread_queue_destroy(&queue, NULL); + +END_TEST + +void *thread_test_thread_queue_timeout2(void *arg) +{ + struct uc_threadqueue *queue = arg; + struct uc_threadmsg *msg; + struct thr_msg *my_msg; + struct timespec timeout = {0, 2000}; + + fail_if(uc_thread_queue_get(queue, &timeout, &msg) != 0); + fail_if(uc_thread_queue_get(queue, &timeout, &msg) != ETIMEDOUT); + + my_msg = (struct thr_msg *)msg; + fail_if(my_msg->b != 12345); + + + return NULL; +} +START_TEST (test_thread_queue_timeout2) + + struct uc_threadqueue queue; + pthread_t tid1; + struct thr_msg my_msg; + + fail_if(uc_thread_queue_init(&queue, 10) != 0); + fail_if(pthread_create(&tid1, NULL, thread_test_thread_queue_timeout2, &queue) != 0); + my_msg.b = 12345; + fail_if(uc_thread_queue_add(&queue, &my_msg.msg) != 0); + + + pthread_join(tid1, NULL); + + uc_thread_queue_destroy(&queue, NULL); + +END_TEST + Suite *threadqueue_suite(void) { @@ -211,6 +259,8 @@ Suite *threadqueue_suite(void) tcase_add_test(tc1, test_thread_queue_reader_writer_len_1); tcase_add_test(tc1, test_thread_queue_zero_len); tcase_add_test(tc1, test_thread_queue_multiple_writers); + tcase_add_test(tc1, test_thread_queue_timeout1); + tcase_add_test(tc1, test_thread_queue_timeout2); //lets start with this: tcase_set_timeout(tc1, 15);