From dc64bed19d4b010275e741d7baae59b02c1cf048 Mon Sep 17 00:00:00 2001 From: Jan Hutter Date: Thu, 3 Nov 2005 19:47:40 +0000 Subject: [PATCH] - code-documentation improved --- Source/charon/job_queue.h | 54 +++++++++++++++++++------------ Source/charon/linked_list.c | 35 ++++++++++++++++---- Source/charon/linked_list.h | 64 +++++++++++++++++++++++++++---------- 3 files changed, 110 insertions(+), 43 deletions(-) diff --git a/Source/charon/job_queue.h b/Source/charon/job_queue.h index 3b6349836..9516c4ebd 100644 --- a/Source/charon/job_queue.h +++ b/Source/charon/job_queue.h @@ -26,36 +26,43 @@ #include "linked_list.h" /** - * Type of Jobs + * Type of Jobs in Job-Queue */ typedef enum job_type_e job_type_t; enum job_type_e{ /** - * Job is to process an incoming IKEv2-Message + * process an incoming IKEv2-Message */ INCOMING_PACKET, /** - * Job is to retransmit an IKEv2-Message + * retransmit an IKEv2-Message */ RETRANSMIT_REQUEST, /** - * Job is to establish an ike sa as initiator + * establish an ike sa as initiator */ ESTABLISH_IKE_SA + /* more job types have to be inserted here */ }; /** - * @brief Job like it is represented in the job queue + * @brief Job as it is stored in the job queue + * + * A job consists of a job-type and an assigned value + * + * The value-type for a specific job is not discussed here */ typedef struct job_s job_t; - struct job_s{ + /** + * Type of job + */ job_type_t type; /** - * Every job has its assigned_data + * Every job has its assigned_data based on the job type */ void * assigned_data; @@ -80,48 +87,55 @@ job_t *job_create(job_type_t type, void *assigned_data); /** * @brief Job-Queue + * + * Despite the job-queue is based on a linked_list_t + * all access functions are thread-save implemented */ typedef struct job_queue_s job_queue_t; struct job_queue_s { /** - * @brief Returns number of jobs in queue + * @brief returns number of jobs in queue * * @param job_queue_t calling object - * @param count integer pointer to store the job count in + * @param[out] count integer pointer to store the job count in * @returns SUCCESS if succeeded, FAILED otherwise */ status_t (*get_count) (job_queue_t *job_queue, int *count); /** - * @brief Get the next job from the queue + * @brief get the next job from the queue * - * If the queue is empty, this function blocks until job can be returned. + * If the queue is empty, this function blocks until a job can be returned. * - * After using, the returned job has to get destroyed. + * After using, the returned job has to get destroyed by the caller. * * @param job_queue_t calling object - * @param job pointer to a job pointer where to job is returned to + * @param[out] job pointer to a job pointer where to job is returned to * @returns SUCCESS if succeeded, FAILED otherwise */ status_t (*get) (job_queue_t *job_queue, job_t **job); /** - * @brief Adds a job to the queue + * @brief adds a job to the queue * - * This function is non blocking + * This function is non blocking and adds a job_t to the list. + * The specific job-object has to get destroyed by the thread which + * removes the job. * * @param job_queue_t calling object - * @param job job to add to the queue (job is not copied) + * @param[in] job job to add to the queue (job is not copied) * @returns SUCCESS if succeeded, FAILED otherwise */ status_t (*add) (job_queue_t *job_queue, job_t *job); /** - * @brief Destroys a job_queue object + * @brief destroys a job_queue object * - * @warning Has only to be called if no other thread is accessing the queue + * @warning The caller of this function has to make sure + * that no thread is going to add or get a job from the job_queue + * after calling this function. * * @param job_queue_t calling object * @returns SUCCESS if succeeded, FAILED otherwise @@ -130,8 +144,8 @@ struct job_queue_s { }; /** - * @brief Creates a job_queue - * * + * @brief Creates an empty job_queue + * * @return job_queue_t empty job_queue */ job_queue_t *job_queue_create(); diff --git a/Source/charon/linked_list.c b/Source/charon/linked_list.c index a0184a8db..c2f138510 100644 --- a/Source/charon/linked_list.c +++ b/Source/charon/linked_list.c @@ -34,17 +34,26 @@ static status_t linked_list_element_destroy(linked_list_element_t *linked_list_element) { linked_list_element_t * this = linked_list_element; + if (this == NULL) + { + return FAILED; + } pfree(this); return SUCCESS; } /* - * Creates a linked list (documented in header-file) + * Creates an empty linked list (described in header-file) */ linked_list_element_t *linked_list_element_create(void *value) { linked_list_element_t *this = alloc_thing(linked_list_element_t, "linked_list_element_t"); + if (this == NULL) + { + return NULL; + } + this->destroy = linked_list_element_destroy; this->previous=NULL; @@ -63,6 +72,11 @@ static status_t insert_first(linked_list_t *linked_list, void *item) linked_list_element_t *element = linked_list_element_create(item); + if (element == NULL) + { + return FAILED; + } + if (this->count == 0) { /* first entry in list */ @@ -70,7 +84,8 @@ static status_t insert_first(linked_list_t *linked_list, void *item) this->last = element; element->previous = NULL; element->next = NULL; - }else + } + else { if ((this->first == NULL) || (this->last == NULL)) { @@ -118,7 +133,7 @@ static status_t remove_first(linked_list_t *linked_list, void **item) this->count--; - return (element->destroy(element)); + return /element->destroy(element)); } /** @@ -152,6 +167,11 @@ static status_t insert_last(linked_list_t *linked_list, void *item) linked_list_element_t *element = linked_list_element_create(item); + if (element == NULL) + { + return FAILED; + } + if (this->count == 0) { /* first entry in list */ @@ -207,7 +227,7 @@ static status_t remove_last(linked_list_t *linked_list, void **item) this->count--; - return element->destroy(element); + return (element->destroy(element)); } /** @@ -239,10 +259,12 @@ static status_t linked_list_destroy(linked_list_t *linked_list) { linked_list_t *this = linked_list; - /* Delete all list items before deleting list */ + /* Remove all list items before destroying list */ while (this->count > 0) { void * value; + /* values are not destroyed so memory leaks are possible + * if list is not empty when deleting */ if (this->remove_first(this,&value) != SUCCESS) { pfree(this); @@ -254,8 +276,7 @@ static status_t linked_list_destroy(linked_list_t *linked_list) } /* - * - * Documented in header + * Described in header */ linked_list_t *linked_list_create() { diff --git a/Source/charon/linked_list.h b/Source/charon/linked_list.h index 91cf0777f..bfaf16034 100644 --- a/Source/charon/linked_list.h +++ b/Source/charon/linked_list.h @@ -25,16 +25,27 @@ #include "types.h" - /** - * @brief Double Linked List Element type + * @brief Element of the linked_list. + * + * This element holds a pointer to the value of the list item itself. */ typedef struct linked_list_element_s linked_list_element_t; struct linked_list_element_s { + /** + * previous list element + * NULL if first element in list + */ linked_list_element_t *previous; + /** + * next list element + * NULL if last element in list + */ linked_list_element_t *next; - /* value of a list item */ + /** + * value of a list item + */ void *value; /** @@ -49,7 +60,9 @@ struct linked_list_element_s { /** * @brief Creates an empty linked list object * - * @param value value of item + * @param[in] value value of item to be set + * + * @warning only the pointer to the value is stored * * @return linked_list_element object */ @@ -57,22 +70,38 @@ linked_list_element_t *linked_list_element_create(void *value); /** - * @brief Double Linked List type + * @brief Double Linked List (named only as linked list) + * + * @warning Access to an object of this type is not thread-save + * + * @see job_queue_t + * @see event_queue_t + * @see send_queue_t */ typedef struct linked_list_s linked_list_t; struct linked_list_s { - /* item count */ + /** + * number of items in the list + */ int count; + /** + * First element in list + * NULL if no elements in list + */ linked_list_element_t *first; + /** + * Last element in list + * NULL if no elements in list + */ linked_list_element_t *last; /** * @brief inserts a new item at the beginning of the list * * @param linked_list calling object - * @param item value to insert in list + * @param[in] item value to insert in list * @returns SUCCESS if succeeded, FAILED otherwise */ status_t (*insert_first) (linked_list_t *linked_list, void *item); @@ -81,16 +110,16 @@ struct linked_list_s { * @brief removes the first item in the list and returns its value * * @param linked_list calling object - * @param item returned value of first item + * @param[in] item returned value of first item * @returns SUCCESS if succeeded, FAILED otherwise */ status_t (*remove_first) (linked_list_t *linked_list, void **item); /** - * @brief Returns the value of the first list item without removing it + * @brief returns the value of the first list item without removing it * * @param linked_list calling object - * @param item returned value of first item + * @param[out] item returned value of first item * @returns SUCCESS if succeeded, FAILED otherwise */ status_t (*get_first) (linked_list_t *linked_list, void **item); @@ -99,7 +128,7 @@ struct linked_list_s { * @brief inserts a new item at the end of the list * * @param linked_list calling object - * @param item value to insert in list + * @param[in] item value to insert into list * @returns SUCCESS if succeeded, FAILED otherwise */ status_t (*insert_last) (linked_list_t *linked_list, void *item); @@ -108,7 +137,7 @@ struct linked_list_s { * @brief removes the last item in the list and returns its value * * @param linked_list calling object - * @param item returned value of last item + * @param[out] item returned value of last item * @returns SUCCESS if succeeded, FAILED otherwise */ status_t (*remove_last) (linked_list_t *linked_list, void **item); @@ -117,7 +146,7 @@ struct linked_list_s { * @brief Returns the value of the last list item without removing it * * @param linked_list calling object - * @param item returned value of last item + * @param[out] item returned value of last item * @returns SUCCESS if succeeded, FAILED otherwise */ status_t (*get_last) (linked_list_t *linked_list, void **item); @@ -125,6 +154,11 @@ struct linked_list_s { /** * @brief Destroys a linked_list object * + * @warning all items are removed before deleting the list. The + * associated values are NOT destroyed. + * Destroying an list which is not empty may cause + * memory leaks! + * * @param linked_list calling object * @returns SUCCESS if succeeded, FAILED otherwise */ @@ -132,9 +166,7 @@ struct linked_list_s { }; /** - * @brief - * - * Creates an empty linked list object + * @brief Creates an empty linked list object */ linked_list_t *linked_list_create(void);