- code documentation improved and made fully compatible with doxygen
authorJan Hutter <jhutter@hsr.ch>
Thu, 10 Nov 2005 08:55:47 +0000 (08:55 -0000)
committerJan Hutter <jhutter@hsr.ch>
Thu, 10 Nov 2005 08:55:47 +0000 (08:55 -0000)
Source/charon/event_queue.c
Source/charon/event_queue.h

index f1b6828..120efd2 100644 (file)
 
 
 /**
- * @brief represents an event as it is stored in the event queue
+ * @brief Represents an event as it is stored in the event queue.
  *
- * A event consists of a event time and an assigned job object
+ * A event consists of a event time and an assigned job object.
  *
  */
 typedef struct event_s event_t;
 
 struct event_s{
        /**
-        * Time to fire the event
+        * Time to fire the event.
         */
        timeval_t time;
 
        /**
-        * Every event has its assigned job
+        * Every event has its assigned job.
         */
        job_t * job;
 
        /**
-        * @brief Destroys a event_t object
+        * @brief Destroys a event_t object.
         *
-        * @param event_t calling object
-        * @returns SUCCESS if succeeded, FAILED otherwise
+        * @param event_t       calling object
+        * @returns                     always SUCCESS
         */
        status_t (*destroy) (event_t *event);
 };
@@ -67,10 +67,6 @@ struct event_s{
  */
 static status_t event_destroy(event_t *event)
 {
-       if (event == NULL)
-       {
-               return FAILED;
-       }
        allocator_free(event);
        return SUCCESS;
 }
@@ -78,17 +74,22 @@ static status_t event_destroy(event_t *event)
 /**
  * @brief Creates a event for a specific time
  *
- * @param time to fire the event
- * @param job job to add to job-queue at specific time
+ * @param time absolute time to fire the event
+ * @param job  job to add to job-queue at specific time
  *
- * @return event_t event object
+ * @returns
+ *                             - created event_t object 
+ *                             - NULL if memory allocation failed
  */
 static event_t *event_create(timeval_t time, job_t *job)
 {
        event_t *this = allocator_alloc_thing(event_t);
+       if (this == NULL)
+       {
+               return this;
+       }
 
        this->destroy = event_destroy;
-
        this->time = time;
        this->job = job;
 
@@ -97,29 +98,33 @@ static event_t *event_create(timeval_t time, job_t *job)
 
 
 /**
- * @brief Private Variables and Functions of event_queue class
+ * @brief Private Variables and Functions of event_queue_t class.
  *
  */
 typedef struct private_event_queue_s private_event_queue_t;
 
 
 struct private_event_queue_s {
+       /**
+        * Public part.
+        */
        event_queue_t public;
 
        /**
-        * The events are stored in a linked list
+        * The events are stored in a linked list of type linked_list_t.
         */
        linked_list_t *list;
 
        /**
-        * access to linked_list is locked through this mutex
+        * Access to linked_list is locked through this mutex.
         */
        pthread_mutex_t mutex;
 
        /**
         * If the queue is empty or an event has not to be fired
-        * a thread has to wait
-        * This condvar is used to wake up such a thread
+        * a thread has to wait.
+        * 
+        * This condvar is used to wake up such a thread.
         */
        pthread_cond_t condvar;
 };
@@ -127,14 +132,14 @@ struct private_event_queue_s {
 /**
  * Returns the difference of to timeval structs in microseconds
  *
- * @param end_time end time
- * @param start_time start time
+ * @param end_time             end time
+ * @param start_time   start time
  *
  * @warning this function is also defined in the tester class
  *                     In later improvements, this function can be added to a general
  *          class type!
  *
- * @return difference in microseconds
+ * @return     difference in microseconds (end time - start time)
  */
 static long time_difference(struct timeval *end_time, struct timeval *start_time)
 {
@@ -147,7 +152,8 @@ static long time_difference(struct timeval *end_time, struct timeval *start_time
 
 
 /**
- * @brief implements function get_count of event_queue_t
+ * Implements function get_count of event_queue_t.
+ * See #event_queue_s.get_count for description.
  */
 static int get_count (private_event_queue_t *this)
 {
@@ -159,7 +165,8 @@ static int get_count (private_event_queue_t *this)
 }
 
 /**
- * @brief implements function get of event_queue_t
+ * Implements function get of event_queue_t.
+ * See #event_queue_s.get for description.
  */
 static status_t get(private_event_queue_t *this, job_t **job)
 {
@@ -216,7 +223,8 @@ static status_t get(private_event_queue_t *this, job_t **job)
 }
 
 /**
- * @brief implements function add of event_queue_t
+ * Implements function add_absolute of event_queue_t.
+ * See #event_queue_s.add_absolute for description.
  */
 static status_t add_absolute(private_event_queue_t *this, job_t *job, timeval_t time)
 {
@@ -297,7 +305,8 @@ static status_t add_absolute(private_event_queue_t *this, job_t *job, timeval_t
 }
 
 /**
- * @brief implements function add of event_queue_t
+ * Implements function add_relative of event_queue_t.
+ * See #event_queue_s.add_relative for description.
  */
 static status_t add_relative(event_queue_t *this, job_t *job, u_int32_t ms)
 {
@@ -315,7 +324,8 @@ static status_t add_relative(event_queue_t *this, job_t *job, u_int32_t ms)
 
 
 /**
- * @brief implements function destroy of event_queue_t
+ * Implements function destroy of event_queue_t.
+ * See #event_queue_s.destroy for description.
  */
 static status_t event_queue_destroy(private_event_queue_t *this)
 {
@@ -342,7 +352,6 @@ static status_t event_queue_destroy(private_event_queue_t *this)
 }
 
 /*
- *
  * Documented in header
  */
 event_queue_t *event_queue_create()
index 32e483b..c517fcd 100644 (file)
@@ -41,14 +41,13 @@ struct event_queue_s {
        /**
         * @brief Returns number of events in queue.
         * 
-        * @param event_queue calling object
-        * @param[out] count integer pointer to store the event count in
-        * @return      number of events in queue
+        * @param event_queue   calling object
+        * @return                              number of events in queue
         */
        int (*get_count) (event_queue_t *event_queue);
 
        /**
-        * @brief get the next job from the event-queue
+        * @brief Get the next job from the event-queue.
         * 
         * If no event is pending, this function blocks until a job can be returned.
         * 
@@ -60,42 +59,46 @@ struct event_queue_s {
        status_t (*get) (event_queue_t *event_queue, job_t **job);
        
        /**
-        * @brief adds a event to the queue, using a relative time
+        * @brief Adds a event to the queue, using a relative time.
         * 
         * This function is non blocking and adds a job_t at a specific time to the list.
         * The specific job-object has to get destroyed by the thread which 
         * removes the job.
         * 
-        * @param event_queue calling object
-        * @param[in] job job to add to the queue (job is not copied)
-        * @param[in] time time, when the event has to get fired
-        * @returns SUCCESS if succeeded, FAILED otherwise
+        * @param event_queue   calling object
+        * @param[in] job               job to add to the queue (job is not copied)
+        * @param[in] time              relative time, when the event has to get fired
+        * @returns 
+        *                                              - SUCCESS if succeeded
+        *                                              - FAILED otherwise
         */
        status_t (*add_relative) (event_queue_t *event_queue, job_t *job, u_int32_t ms);
        
        /**
-        * @brief adds a event to the queue, using an absolute time
+        * @brief Adds a event to the queue, using an absolute time.
         * 
         * This function is non blocking and adds a job_t at a specific time to the list.
         * The specific job-object has to get destroyed by the thread which 
         * removes the job.
         * 
-        * @param event_queue calling object
-        * @param[in] job job to add to the queue (job is not copied)
-        * @param[in] time time, when the event has to get fired
-        * @returns SUCCESS if succeeded, FAILED otherwise
+        * @param event_queue   calling object
+        * @param[in]                   job job to add to the queue (job is not copied)
+        * @param[in]                   absolute time time, when the event has to get fired
+        * @returns
+        *                                              - SUCCESS if succeeded
+        *                                              - FAILED otherwise
         */
        status_t (*add_absolute) (event_queue_t *event_queue, job_t *job, timeval_t time);
 
        /**
-        * @brief destroys a event_queue object
+        * @brief Destroys a event_queue object.
         * 
         * @warning The caller of this function has to make sure
         * that no thread is going to add or get an event from the event_queue
         * after calling this function.
         * 
-        * @param event_queue calling object
-        * @returns SUCCESS if succeeded, FAILED otherwise
+        * @param event_queue   calling object
+        * @returns                             always SUCCESS
         */
        status_t (*destroy) (event_queue_t *event_queue);
 };
@@ -103,7 +106,9 @@ struct event_queue_s {
 /**
  * @brief Creates an empty event_queue
  * 
- * @return empty event_queue object
+ * @returns 
+ *                     - Empty event_queue_t object
+ *                     - NULL if memory allocation failed
  */
 event_queue_t *event_queue_create();
 #endif /*EVENT_QUEUE_H_*/