- docs updated
authorMartin Willi <martin@strongswan.org>
Tue, 6 Dec 2005 16:46:39 +0000 (16:46 -0000)
committerMartin Willi <martin@strongswan.org>
Tue, 6 Dec 2005 16:46:39 +0000 (16:46 -0000)
12 files changed:
Source/charon/queues/event_queue.c
Source/charon/queues/event_queue.h
Source/charon/queues/job_queue.c
Source/charon/queues/job_queue.h
Source/charon/queues/jobs/delete_established_ike_sa_job.h
Source/charon/queues/jobs/delete_half_open_ike_sa_job.h
Source/charon/queues/jobs/incoming_packet_job.h
Source/charon/queues/jobs/initiate_ike_sa_job.h
Source/charon/queues/jobs/job.h
Source/charon/queues/jobs/retransmit_request_job.h
Source/charon/queues/send_queue.c
Source/charon/queues/send_queue.h

index c641a5a..741fe14 100644 (file)
@@ -90,7 +90,7 @@ static event_t *event_create(timeval_t time, job_t *job)
 typedef struct private_event_queue_t private_event_queue_t;
 
 /**
- * @brief Private Variables and Functions of event_queue_t class.
+ * Private Variables and Functions of event_queue_t class.
  *
  */
 struct private_event_queue_t {
@@ -342,7 +342,7 @@ event_queue_t *event_queue_create()
        this->public.add_relative = (void (*) (event_queue_t *event_queue, job_t *job, u_int32_t ms)) add_relative;
        this->public.destroy = (void (*) (event_queue_t *event_queue)) event_queue_destroy;
 
-       this->list = linked_list_create();;
+       this->list = linked_list_create();
        pthread_mutex_init(&(this->mutex), NULL);
        pthread_cond_init(&(this->condvar), NULL);
 
index 41700cf..a604241 100644 (file)
@@ -32,10 +32,18 @@ typedef struct event_queue_t event_queue_t;
 
 /**
  * @brief Event-Queue used to store timed events.
+ * 
+ * Added events are sorted. The get method blocks until
+ * the time is elapsed to process the next event. The get 
+ * method is called from the scheduler_t thread, which
+ * will add the jobs to to job_queue_t for further processing.
  *
  * Although the event-queue is based on a linked_list_t
  * all access functions are thread-save implemented.
  * 
+ * @b Constructors:
+ * - event_queue_create()
+ * 
  * @ingroup queues
  */
 struct event_queue_t {
@@ -93,15 +101,14 @@ struct event_queue_t {
         * after calling this function.
         *
         * @param event_queue   calling object
-        * @returns                             always SUCCESS
         */
        void (*destroy) (event_queue_t *event_queue);
 };
 
 /**
- * @brief Creates an empty event_queue
+ * @brief Creates an empty event_queue.
  *
- * @returns            event_queue
+ * @returns event_queue_t object
  * 
  * @ingroup queues
  */
index d6e8f6b..9d383d7 100644 (file)
@@ -36,12 +36,17 @@ typedef struct private_job_queue_t private_job_queue_t;
  *
  */
 struct private_job_queue_t {
+       
+       /**
+        * public members
+        */
        job_queue_t public;
 
        /**
         * The jobs are stored in a linked list
         */
        linked_list_t *list;
+       
        /**
         * access to linked_list is locked through this mutex
         */
index 48b6f07..9fcf080 100644 (file)
 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.
  * 
+ * @b Constructors:
+ * - job_queue_create()
+ * 
  * @ingroup queues
  */
 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
@@ -47,7 +52,7 @@ struct job_queue_t {
        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.
@@ -59,7 +64,7 @@ struct job_queue_t {
        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
@@ -71,7 +76,7 @@ struct job_queue_t {
        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
@@ -85,7 +90,7 @@ struct job_queue_t {
 /**
  * @brief Creates an empty job_queue.
  *
- * @return job_queue_t empty job_queue
+ * @return job_queue_t object
  * 
  * @ingroup queues
  */
index c2e1d8d..762dcea 100644 (file)
@@ -33,6 +33,9 @@ typedef struct delete_established_ike_sa_job_t delete_established_ike_sa_job_t;
 /**
  * @brief Class representing an DELETE_ESTABLISHED_IKE_SA Job.
  * 
+ * This job initiates the deletion of an IKE_SA. The SA
+ * to delete is specified via an ike_sa_id_t.
+ * 
  * @b Constructors:
  *  - delete_established_ike_sa_job_create()
  * 
@@ -66,7 +69,7 @@ struct delete_established_ike_sa_job_t {
  * @brief Creates a job of type DELETE_ESTABLISHED_IKE_SA.
  * 
  * @param ike_sa_id            id of the IKE_SA to delete
- * @return                             created delete_established_ike_sa_job_t object
+ * @return                             delete_established_ike_sa_job_t object
  * 
  * @ingroup jobs
  */
index 39b7518..ea42be8 100644 (file)
@@ -33,6 +33,10 @@ typedef struct delete_half_open_ike_sa_job_t delete_half_open_ike_sa_job_t;
 /**
  * @brief Class representing an DELETE_HALF_OPEN_IKE_SA Job.
  * 
+ * This job is responsible for deleting of half open IKE_SAs. A half 
+ * open IKE_SA is every IKE_SA which hasn't reache the ike_sa_established
+ * state.
+ * 
  * @b Constructors:
  *  - delete_half_open_ike_sa_job_create()
  * 
index d57809d..e3fb579 100644 (file)
 typedef struct incoming_packet_job_t incoming_packet_job_t;
 
 /**
- * @brief Object representing an INCOMING_PACKET Job.
+ * @brief Class representing an INCOMING_PACKET Job.
+ * 
+ * An incoming pack job is created from the receiver, which has
+ * read a packet to process from the socket.
+ * 
+ * @b Constructors:
+ * - incoming_packet_job_create()
  * 
  * @ingroup jobs
  */
index a382181..ec6e4c1 100644 (file)
 typedef struct initiate_ike_sa_job_t initiate_ike_sa_job_t;
 
 /**
- * Object representing an INITIATE_IKE_SA Job
+ * @brief Class representing an INITIATE_IKE_SA Job.
+ * 
+ * This job is created if an IKE_SA should be iniated. This 
+ * happens form a user request, or via the kernel interface.
+ * 
+ * @b Constructors:
+ * - initiate_ike_sa_job_create()
  * 
  * @ingroup jobs
  */
@@ -39,14 +45,14 @@ struct initiate_ike_sa_job_t {
        job_t job_interface;
        
        /**
-        * @brief Returns the currently set configuration name for this job
+        * @brief Returns the currently set configuration name for this job.
         *      
         * @warning Returned name is not copied.
         * 
         * @param this  calling initiate_ike_sa_job_t object
         * @return              name of the configuration
         */
-       char * (*get_configuration_name) (initiate_ike_sa_job_t *this);
+       char *(*get_configuration_name) (initiate_ike_sa_job_t *this);
 
        /**
         * @brief Destroys an initiate_ike_sa_job_t object.
index 89e9c5b..eea4da0 100644 (file)
@@ -32,6 +32,8 @@ typedef enum job_type_t job_type_t;
 /**
  * @brief Definition of the various job types.
  * 
+ * @todo add more jobs, such as rekeying.
+ * 
  * @ingroup jobs
  */
 enum job_type_t {
@@ -52,8 +54,8 @@ enum job_type_t {
         * 
         * Job is implemented in class type initiate_ike_sa_job_t
         */
-       
        INITIATE_IKE_SA,
+       
        /** 
         * Delete an ike sa which is still not established.
         * 
@@ -67,13 +69,12 @@ enum job_type_t {
         * Job is implemented in class type delete_established_ike_sa_job_t
         */     
        DELETE_ESTABLISHED_IKE_SA
-       
-       
-       /* more job types have to be inserted here */
 };
 
 /**
  * string mappings for job_type_t
+ * 
+ * @ingroup jobs
  */
 extern mapping_t job_type_m[];
 
@@ -85,6 +86,9 @@ typedef struct job_t job_t;
  * 
  * A job consists of a job-type and one or more assigned values.
  * 
+ * @b Constructors:
+ * - None, use specific implementation of the interface.
+ * 
  * @ingroup jobs
  */
 struct job_t {
index 0573f04..b608526 100644 (file)
 typedef struct retransmit_request_job_t retransmit_request_job_t;
 
 /**
- * Object representing an RETRANSMIT_REQUEST Job.
+ * @brief Class representing an RETRANSMIT_REQUEST Job.
+ * 
+ * This job is scheduled every time a request is sent over the
+ * wire. If the response to the request is not received at schedule
+ * time, the retransmission will be initiated.
+ * 
+ * @b Constructors:
+ * - retransmit_request_job_create()
  * 
  * @ingroup jobs
  */
index 25ad1aa..df1f7b3 100644 (file)
@@ -30,7 +30,7 @@
 
 typedef struct private_send_queue_t private_send_queue_t;
 
- /**
+/**
  * @brief Private Variables and Functions of send_queue class
  *
  */
@@ -70,7 +70,7 @@ static int get_count(private_send_queue_t *this)
        return count;
 }
 
- /**
+/**
  * implements send_queue_t.get
  */
 static packet_t *get(private_send_queue_t *this)
@@ -96,7 +96,7 @@ static packet_t *get(private_send_queue_t *this)
        return packet;
 }
 
- /**
+/**
  * implements send_queue_t.add
  */
 static void add(private_send_queue_t *this, packet_t *packet)
@@ -107,7 +107,7 @@ static void add(private_send_queue_t *this, packet_t *packet)
        pthread_mutex_unlock(&(this->mutex));
 }
 
- /**
+/**
  * implements send_queue_t.destroy
  */
 static void destroy (private_send_queue_t *this)
@@ -133,7 +133,7 @@ static void destroy (private_send_queue_t *this)
        allocator_free(this);
 }
 
- /*
+/*
  *
  * Documented in header
  */
index 646d7ad..6dc5867 100644 (file)
 typedef struct send_queue_t send_queue_t;
 
 /**
- * @brief Send-Queue
- *
+ * @brief The send queue stores packet for the sender_t instance.
+ * 
+ * The sender_t will send them consequently over the wire.
  * Although the send-queue is based on a linked_list_t
  * all access functions are thread-save implemented.
  * 
+ * @b Constructors:
+ * - send_queue_create()
+ * 
  * @ingroup queues
  */
 struct send_queue_t {
@@ -87,7 +91,7 @@ struct send_queue_t {
 /**
  * @brief Creates an empty send_queue_t.
  *
- * @return send_queue_t empty send_queue_t
+ * @return send_queue_t object
  * 
  * @ingroup queues
  */