From bb761bafb89a734fdc98a8e12cfff3b0c16fb0af Mon Sep 17 00:00:00 2001 From: Matthias Schiffer Date: Tue, 10 Nov 2015 22:00:15 +0100 Subject: Add lots of missing doxygen comments --- src/iface.c | 3 +++ src/pqueue.c | 10 ++++++++++ src/pqueue.h | 10 ++++++---- src/status.c | 1 + src/task.c | 4 ++++ src/task.h | 9 +++++++-- 6 files changed, 31 insertions(+), 6 deletions(-) diff --git a/src/iface.c b/src/iface.c index 4f55807..b944d23 100644 --- a/src/iface.c +++ b/src/iface.c @@ -144,6 +144,7 @@ static void open_iface_linux(fastd_iface_t *iface, const char *ifname, uint16_t iface->fd.fd = -1; } +/** Removes TUN/TAP interfaces on platforms which need this */ static void cleanup_iface(UNUSED fastd_iface_t *iface) { } @@ -190,6 +191,7 @@ static void set_tun_mtu(fastd_iface_t *iface, uint16_t mtu) { exit_errno("TUNSIFINFO ioctl failed"); } +/** Removes TUN/TAP interfaces on platforms which need this */ static void cleanup_iface(fastd_iface_t *iface) { if (!iface->cleanup) return; @@ -396,6 +398,7 @@ static void open_iface(fastd_iface_t *iface, const char *ifname, uint16_t mtu) { exit_errno("SIOCSIFMTU ioctl failed"); } +/** Removes TUN/TAP interfaces on platforms which need this */ static void cleanup_iface(UNUSED fastd_iface_t *iface) { } diff --git a/src/pqueue.c b/src/pqueue.c index d80935f..b292bf7 100644 --- a/src/pqueue.c +++ b/src/pqueue.c @@ -36,6 +36,7 @@ #include "log.h" +/** Links an element at the position specified by \e pqueue */ static inline void pqueue_link(fastd_pqueue_t **pqueue, fastd_pqueue_t *elem) { if (elem->next) exit_bug("pqueue_link: element already linked"); @@ -48,6 +49,7 @@ static inline void pqueue_link(fastd_pqueue_t **pqueue, fastd_pqueue_t *elem) { *pqueue = elem; } +/** Unlinks an element */ static inline void pqueue_unlink(fastd_pqueue_t *elem) { *elem->pprev = elem->next; if (elem->next) @@ -57,6 +59,11 @@ static inline void pqueue_unlink(fastd_pqueue_t *elem) { } +/** + Merges two priority queues + + \e pqueue2 may be empty (NULL) +*/ static fastd_pqueue_t * pqueue_merge(fastd_pqueue_t *pqueue1, fastd_pqueue_t *pqueue2) { if (!pqueue1) exit_bug("pqueue_merge: pqueue1 unset"); @@ -85,6 +92,7 @@ static fastd_pqueue_t * pqueue_merge(fastd_pqueue_t *pqueue1, fastd_pqueue_t *pq return lo; } +/** Merges a list of priority queues */ static fastd_pqueue_t * pqueue_merge_pairs(fastd_pqueue_t *pqueue0) { if (!pqueue0) return NULL; @@ -104,6 +112,7 @@ static fastd_pqueue_t * pqueue_merge_pairs(fastd_pqueue_t *pqueue0) { return pqueue_merge(pqueue_merge(pqueue0, pqueue1), pqueue_merge_pairs(pqueue2)); } +/** Inserts a new element into a priority queue */ void fastd_pqueue_insert(fastd_pqueue_t **pqueue, fastd_pqueue_t *elem) { if (elem->pprev || elem->next || elem->children) exit_bug("fastd_pqueue_insert: tried to insert linked pqueue element"); @@ -112,6 +121,7 @@ void fastd_pqueue_insert(fastd_pqueue_t **pqueue, fastd_pqueue_t *elem) { (*pqueue)->pprev = pqueue; } +/** Removes an element from a priority queue */ void fastd_pqueue_remove(fastd_pqueue_t *elem) { if (!fastd_pqueue_linked(elem)) { if (elem->children || elem->next) diff --git a/src/pqueue.h b/src/pqueue.h index 126c3ea..8978a84 100644 --- a/src/pqueue.h +++ b/src/pqueue.h @@ -34,16 +34,18 @@ #include "types.h" +/** Element of a priority queue */ struct fastd_pqueue { - fastd_pqueue_t **pprev; - fastd_pqueue_t *next; + fastd_pqueue_t **pprev; /**< \e next element of the previous element (or \e children of the parent) */ + fastd_pqueue_t *next; /**< Next sibling in the heap */ - fastd_pqueue_t *children; + fastd_pqueue_t *children; /**< Heap children */ - int64_t value; + int64_t value; /**< The priority */ }; +/** Checks if an element is currently part of a priority queue */ static inline bool fastd_pqueue_linked(fastd_pqueue_t *elem) { return elem->pprev; } diff --git a/src/status.c b/src/status.c index 80ce203..f6ab09f 100644 --- a/src/status.c +++ b/src/status.c @@ -208,6 +208,7 @@ static void dump_status(int fd) { } } +/** Deletes the status socket file */ static void unlink_status_socket(void) { if (!conf.status_socket || ctx.status_fd.fd < 0) return; diff --git a/src/task.c b/src/task.c index 44a8ebf..aa6225a 100644 --- a/src/task.c +++ b/src/task.c @@ -41,6 +41,7 @@ static inline void maintenance(void) { fastd_task_reschedule_relative(&ctx.next_maintenance, MAINTENANCE_INTERVAL); } +/** Handles one task */ static void handle_task(void) { fastd_task_t *task = container_of(ctx.task_queue, fastd_task_t, entry); fastd_pqueue_remove(ctx.task_queue); @@ -59,16 +60,19 @@ static void handle_task(void) { } } +/** Handles all tasks whose timeout has been reached */ void fastd_task_handle(void) { while (ctx.task_queue && fastd_timed_out(ctx.task_queue->value)) handle_task(); } +/** Puts a task back into the queue with a new timeout */ void fastd_task_reschedule(fastd_task_t *task, fastd_timeout_t timeout) { task->entry.value = timeout; fastd_pqueue_insert(&ctx.task_queue, &task->entry); } +/** Gets the timeout of the next task (if any) */ bool fastd_task_timeout(fastd_timeout_t *timeout) { if (!ctx.task_queue) return false; diff --git a/src/task.h b/src/task.h index 4c00207..91bacc0 100644 --- a/src/task.h +++ b/src/task.h @@ -34,9 +34,10 @@ #include "pqueue.h" +/** A scheduled task */ struct fastd_task { - fastd_pqueue_t entry; - fastd_task_type_t type; + fastd_pqueue_t entry; /**< Task queue entry */ + fastd_task_type_t type; /**< Type of the task */ }; @@ -45,18 +46,22 @@ void fastd_task_handle(void); void fastd_task_reschedule(fastd_task_t *task, fastd_timeout_t timeout); +/** Checks if the given task is currently scheduled */ static inline bool fastd_task_scheduled(fastd_task_t *task) { return fastd_pqueue_linked(&task->entry); } +/** Removes a task from the queue */ static inline void fastd_task_unschedule(fastd_task_t *task) { fastd_pqueue_remove(&task->entry); } +/** Puts a task back into the queue with a new timeout relative to the old one */ static inline void fastd_task_reschedule_relative(fastd_task_t *task, int64_t delay) { fastd_task_reschedule(task, task->entry.value + delay); } +/** Schedules a task with given type and timeout */ static inline void fastd_task_schedule(fastd_task_t *task, fastd_task_type_t type, fastd_timeout_t timeout) { task->type = type; fastd_task_reschedule(task, timeout); -- cgit v1.2.3