- docs updated

[strongswan.git] / Source / charon / queues / job_queue.h

diff --git a/Source/charon/queues/job_queue.h b/Source/charon/queues/job_queue.h
index f5030ac..9fcf080 100644 (file)
--- a/Source/charon/queues/job_queue.h
+++ b/Source/charon/queues/job_queue.h
@@ -1,7 +1,7 @@
 /**
  * @file job_queue.h
  *
- * @brief Job-Queue based on linked_list_t
+ * @brief Interface of job_queue_t.
  *
  */
 
@@ -24,69 +24,76 @@
 #define JOB_QUEUE_H_
 
 #include <types.h>
-#include <jobs/job.h>
+#include <queues/jobs/job.h>
+
+typedef struct job_queue_t job_queue_t;
 
 /**
- * @brief Job-Queue
+ * @brief The job queue stores jobs, which will be processed by the thread_pool_t.
  *
+ * Jobs are added from various sources, from the threads and 
+ * from the event_queue_t.
  * Although the job-queue is based on a linked_list_t
- * all access functions are thread-save implemented
+ * all access functions are thread-save implemented.
+ * 
+ * @b Constructors:
+ * - job_queue_create()
+ * 
+ * @ingroup queues
  */
-typedef struct job_queue_s job_queue_t;
-
-struct job_queue_s {
+struct job_queue_t {
 
        /**
-        * @brief returns number of jobs in queue
+        * @brief Returns number of jobs in queue.
         *
-        * @param job_queue_t calling object
-        * @returns number of items in queue
+        * @param job_queue_t   calling object
+        * @returns                     number of items in queue
         */
        int (*get_count) (job_queue_t *job_queue);
 
        /**
-        * @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 a job can be returned.
-        *
         * After using, the returned job has to get destroyed by the caller.
         *
-        * @param job_queue_t calling object
-        * @param[out] job pointer to a job pointer where to job is returned to
-        * @returns SUCCESS if succeeded, FAILED otherwise
+        * @param job_queue_t   calling object
+        * @param[out] job              pointer to a job pointer where to job is returned to
+        * @return                              next job
         */
-       status_t (*get) (job_queue_t *job_queue, job_t **job);
+       job_t *(*get) (job_queue_t *job_queue);
 
        /**
-        * @brief adds a job to the queue
+        * @brief Adds a job to the queue.
         *
         * 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[in] job job to add to the queue (job is not copied)
-        * @returns SUCCESS if succeeded, FAILED otherwise
+        * @param job_queue_t   calling object
+        * @param job                   job to add to the queue (job is not copied)
         */
-       status_t (*add) (job_queue_t *job_queue, job_t *job);
+       void (*add) (job_queue_t *job_queue, job_t *job);
 
        /**
-        * @brief destroys a job_queue object
+        * @brief Destroys a job_queue object.
         *
         * @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
+        * @param job_queue_t   calling object
         */
-       status_t (*destroy) (job_queue_t *job_queue);
+       void (*destroy) (job_queue_t *job_queue);
 };
 
 /**
- * @brief Creates an empty job_queue
+ * @brief Creates an empty job_queue.
  *
- * @return job_queue_t empty job_queue
+ * @return job_queue_t object
+ * 
+ * @ingroup queues
  */
 job_queue_t *job_queue_create();
+
 #endif /*JOB_QUEUE_H_*/