- code-documentation improved
This commit is contained in:
parent
ef23cd28c1
commit
dc64bed19d
3 changed files with 110 additions and 43 deletions
|
@ -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();
|
||||
|
|
|
@ -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()
|
||||
{
|
||||
|
|
|
@ -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);
|
||||
|
||||
|
|
Loading…
Reference in a new issue