- code-documentation improved
authorJan Hutter <jhutter@hsr.ch>
Thu, 3 Nov 2005 19:47:40 +0000 (19:47 -0000)
committerJan Hutter <jhutter@hsr.ch>
Thu, 3 Nov 2005 19:47:40 +0000 (19:47 -0000)
Source/charon/job_queue.h
Source/charon/linked_list.c
Source/charon/linked_list.h

index 3b63498..9516c4e 100644 (file)
 #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 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();
index a0184a8..c2f1385 100644 (file)
 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() 
 {
index 91cf077..bfaf160 100644 (file)
 
 #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);