- code documentation improved and made fully compatible with doxygen
This commit is contained in:
parent
69dd95811f
commit
f4fae0beae
2 changed files with 61 additions and 47 deletions
|
@ -34,29 +34,29 @@
|
|||
|
||||
|
||||
/**
|
||||
* @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()
|
||||
|
|
|
@ -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_*/
|
||||
|
|
Loading…
Reference in a new issue