Trim more fat, add some doxygen markup to the threadpool functions

6 files changed, 160 insertions, 61 deletions

diff --git a/src/encryption.c b/src/encryption.c
index b6832ed..89448e8 100644
--- a/src/encryption.c
+++ b/src/encryption.c
@@ -286,6 +286,45 @@ void* xsodium_malloc(size_t size) {
 }
 
 
+
+/*
+
+#include "threadpool.h"
+
+// #include <stdlib.h>
+// #include <dirent.h>
+// #include <string.h>
+// #include <errno.h>
+// #include <error.h>
+
+// dlinkedlist * scandirlist(const char * const dir, int (*selector)(const struct dirent *), int (*cmp)(const struct dirent **, const struct dirent **)) {
+//     if(!dir || selector == NULL || cmp == NULL) ERRRET(EINVAL, NULL);
+    
+//     struct dirent **namelist = NULL;
+//     dlinkedlist *list = NULL;
+//     int numentries = -1;
+
+//     if((numentries = scandir(dir, &namelist, selector, cmp)) < 0)
+//         ERRRET(errno, NULL);
+
+//     list = dlinkedlist_init();
+//     for(int i = 0; i < numentries; i++)
+//         if(dlinkedlist_append(list, (void *)(namelist[i]), free) < 0) {
+//             dlinkedlist_free(list);
+//             for(int j = i; j < numentries; j++)
+//                 free(namelist[j]);
+
+//             free(namelist);
+//             ERRRET(errno, NULL);
+//         }
+//     free(namelist);
+
+//     return list;
+// }
+
+// TODO: Rewrite this to use the threadpool. Each newly scanned file should be pushed onto the threadpool as an encryption task
+*/
+
 /*
 int main(void) {
     // Example code for creating a temp file, writing to it, then linking it back into the fs
diff --git a/src/scanner.c b/src/scanner.c
deleted file mode 100644
index 2ffbea4..0000000
--- a/src/scanner.c
+++ /dev/null
@@ -1,37 +0,0 @@
-#define _GNU_SOURCE
-#include "shared.h"
-
-#include "scanner.h"
-
-#include <stdlib.h>
-#include <dirent.h>
-#include <string.h>
-#include <errno.h>
-#include <error.h>
-
-// dlinkedlist * scandirlist(const char * const dir, int (*selector)(const struct dirent *), int (*cmp)(const struct dirent **, const struct dirent **)) {
-//     if(!dir || selector == NULL || cmp == NULL) ERRRET(EINVAL, NULL);
-    
-//     struct dirent **namelist = NULL;
-//     dlinkedlist *list = NULL;
-//     int numentries = -1;
-
-//     if((numentries = scandir(dir, &namelist, selector, cmp)) < 0)
-//         ERRRET(errno, NULL);
-
-//     list = dlinkedlist_init();
-//     for(int i = 0; i < numentries; i++)
-//         if(dlinkedlist_append(list, (void *)(namelist[i]), free) < 0) {
-//             dlinkedlist_free(list);
-//             for(int j = i; j < numentries; j++)
-//                 free(namelist[j]);
-
-//             free(namelist);
-//             ERRRET(errno, NULL);
-//         }
-//     free(namelist);
-
-//     return list;
-// }
-
-// TODO: Rewrite this to use the threadpool. Each newly scanned file should be pushed onto the threadpool as an encryption task
\ No newline at end of file
diff --git a/src/scanner.h b/src/scanner.h
deleted file mode 100644
index b9f2f9a..0000000
--- a/src/scanner.h
+++ /dev/null
@@ -1,5 +0,0 @@
-#ifndef __VXGG_REWRITE___SCANNER_H___7164133769617___
-#define __VXGG_REWRITE___SCANNER_H___7164133769617___
-
-
-#endif
\ No newline at end of file
diff --git a/src/shared.h b/src/shared.h
index efb95ad..3ff7b2d 100644
--- a/src/shared.h
+++ b/src/shared.h
@@ -3,11 +3,11 @@
 
 #include <stddef.h>
 
-#define STATIC_ARRAY_LEN(arr) (sizeof((arr))/sizeof((arr)[0]))
-
 typedef int (*gcallback)(void*);    // Generic callback signature
 typedef void (*fcallback)(void*);   // free()-like callback signature
 
+#define STATIC_ARRAY_LEN(arr) (sizeof((arr))/sizeof((arr)[0]))
+
 #define ERRRET(errval, retval) do {\
     errno = (errval);\
     return (retval);\
@@ -37,6 +37,7 @@ typedef void (*fcallback)(void*);   // free()-like callback signature
 
 // Error macro that gcc will not complain about
 #define ERROR(status, errnum, format, ...) do {error((status), (errnum), (format)__VA_ARGS__); exit((status));} while (0)
+// Spit out a warning using `error`
 #define WARN(errnum, format, ...) do {error(0, (errnum), (format)__VA_ARGS__);} while (0)
 
 // Read the entire contents of a file descriptor into a malloc()'ed buffer
diff --git a/src/threadpool.c b/src/threadpool.c
index bd52c75..681428e 100644
--- a/src/threadpool.c
+++ b/src/threadpool.c
@@ -369,8 +369,10 @@ static int __CTQ_CONSUMER(void *ctq) {
         task_free(ctask);
     }
 
-    thrd_exit(1); // non-zero indicates error, -1 indicates invalid argument
+    thrd_exit(1);
 }
+// TODO: Make this function return 0 or -1 depending on whether the overall ctq has been canceled or not. Canceling shouldn't 
+// be treated as an error
 
 int ctqueue_start(ctqueue *ctq) {
     if(!ctq) ERRRET(EINVAL, -1);
diff --git a/src/threadpool.h b/src/threadpool.h
index 7fda6f5..1d9a537 100644
--- a/src/threadpool.h
+++ b/src/threadpool.h
@@ -8,43 +8,142 @@ typedef struct task task;
 typedef struct taskqueue taskqueue;
 typedef struct ctqueue ctqueue;
 
-// Create a new task. Sets `errno` and returns `NULL` on error
+/**
+ * @brief Create a task
+ * 
+ * @param callback Callback function the given data should be ran with. Must be non-null
+ * @param freecb Callback function for freeing the given data. May be null
+ * @param data Data to be passed to the callback. May be null
+ * @return task* Returns a task object with set parameters. Returns `null` and sets errno on error
+ */
 task * task_init(gcallback callback, fcallback freecb, void *data);
-// Free a task. Passes the `.data` member to specified fcallback as a function parameter. Does not return a value or set `errno`
+
+/**
+ * @brief Free a task
+ * 
+ * @param tsk A task object to free. Frees data associated with task via `freecb` value specified in its creation. May be null
+ */
 void task_free(void *tsk);
-// Fire a task. Passes the `.data` member to specified gcallback as a function parameter. Returns value of gcallback, or sets `errno` and returns `-1` on error
+
+/**
+ * @brief Fire a task. Passes the `data` member to the specified `callback`
+ * 
+ * @param tsk A task to be fired. Must be non-null
+ * @return int Returns value of the fired callback. Returns -1 and sets errno on error
+ */
 int task_fire(task *tsk);
-// Fire and free a task simultaneously. Calls specified gcallback and fcallback on associated data. Returns value of gcallback, or sets `errno` and returns `-1` on error
+
+/**
+ * @brief Fire and destroy a task simultaneously. Calls specified callback and free-callback on associated data
+ * 
+ * @param tsk Task to be fired and destroyed. Must be non-null
+ * @return int Returns value of the callback. Returns -1 and sets errno on error
+ */
 int task_fired(task *tsk);                                              
 
 
 
-// Create a FIFO queue of task objects. Returns a new taskqueue on success, sets `errno` and returns `NULL` on error
+/**
+ * @brief Create a FIFO queue of tasks
+ * 
+ * @return taskqueue* Returns a new taskqueue object. Returns `null` and sets errno on error
+ */
 taskqueue * taskqueue_init(void);
-// Free a taskqueue. Does not return a value or set `errno`
+
+/**
+ * @brief Free a taskqueue
+ * 
+ * @param tq A taskqueue to be freed. May be null
+ */
 void taskqueue_free(void *tq);
-// Push a task onto the queue. Returns 0 on success, sets `errno` and returns `-1` on error
+
+/**
+ * @brief Push a task onto a taskqueue
+ * 
+ * @param tq The taskqueue to be modified. Must be non-null
+ * @param tsk The task to push. Must be non-null
+ * @return int Returns 0 on success, sets errno and returns -1 on error
+ */
 int taskqueue_push(taskqueue *tq, task *tsk);
-// Pop a task from the queue. Returns a task on success, sets `errno` and returns `NULL` on error
+
+/**
+ * @brief Pop a task from a taskqueue
+ * 
+ * @param tq A taskqueue to grab a task from. Must be non-null
+ * @return task* Returns a task on success, sets errno and returns `null` on error
+ */
 task * taskqueue_pop(taskqueue *tq);
-// Push a task to the front of the queue (append, task becomes first in line to be popped). Returns 0 on success, sets `errno` and returns `-1` on error
+
+/**
+ * @brief Append a task to the front of a taskqueue
+ * 
+ * @param tq The taskqueue to be modified. Must be non-null
+ * @param tsk The task to be appended. Must be non-null
+ * @return int Returns 0 on success, sets errno and returns `null` on error
+ */
 int taskqueue_pushfront(taskqueue *tq, task *tsk);
-// Pop a task from the back of the queue (pop the most recently (normally) pushed item). Returns a task on success, sets `errno` and returns `NULL` on error
+
+/**
+ * @brief Pop a task from the back (most recently pushed task) of a taskqueue
+ * 
+ * @param tq A taskqueue to pop from. Must be non-null
+ * @return task* Returns a task on success, sets errno and returns `null` on error
+ */
 task * taskqueue_popback(taskqueue *tq);
 
 
 
-// Create a concurrent taskqueue with `size` allocated threads
+/**
+ * @brief Create a concurrent taskqueue with `size` allocated threads
+ * 
+ * @param size Number of threads in the threadpool. Must be greater than zero
+ * @return ctqueue* Returns a new ctqueue, sets errno and returns `null` on error
+ */
 ctqueue * ctqueue_init(int size);
-// Cancel a currently running ctq
+
+/**
+ * @brief Cancel all tasks being processed in a currently running concurrent taskqueue
+ * 
+ * @param ctq The concurrent taskqueue to be canceled. Must be non-null
+ * @return int Returns 0 on success, sets errno and returns -1 on error
+ */
 int ctqueue_cancel(ctqueue *ctq);
-// Free a ctq (cancels any remaining operations)
+
+/**
+ * @brief Free a concurrent taskqueue
+ * @attention This cancels all currently running threads via `ctqueue_cancel`
+ *
+ * @param ctq The concurrent taskqueue to free. May be null
+ */
 void ctqueue_free(void *ctq);
-// Push a new task to the queue, waiting via mutex to do so
+
+/**
+ * @brief Push a task onto a concurrent taskqueue
+ * @attention May block for an indefinite amount of time to push the task
+ * 
+ * @param ctq The concurrent taskqueue to modify. Must be non-null
+ * @param tsk The task to push. Must be non-null
+ * @return Returns `thrd_success` on success, returns `thrd_error` or `thrd_nomem` on error
+ */
 int ctqueue_waitpush(ctqueue *ctq, task *tsk);
-// Pop a task from the queue, waiting via mutex to do so
+
+
+/**
+ * @brief Pop a task from the concurrent taskqueue
+ * @attention May block for an indefinite amount of time to pop the task
+ * 
+ * @param ctq The concurrent taskqueue to pop from. Must be non-null
+ * @return Returns a task on success, sets errno and returns `null` on error
+ */
 task * ctqueue_waitpop(ctqueue *ctq);
-// Spawn the allocated threads for a ctq
+
+/**
+ * @brief Start the threads allocated to a concurrent taskqueue
+ * @attention Threads will not consume pushed tasks until this function is ran 
+ *
+ * @param ctq A concurrent taskqueue to start. Must be non-null
+ * @return int Returns 0 on success, sets errno and returns -1 on error
+ */
 int ctqueue_start(ctqueue *ctq);
 
 #endif
\ No newline at end of file