From 1444c72db8505340c0988ea286a29bc261297933 Mon Sep 17 00:00:00 2001
From: "@syxhe" <https://t.me/syxhe>
Date: Mon, 9 Jun 2025 17:43:50 -0500
Subject: We do a little documentation

---
 src/threadpool.c | 60 +++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 44 insertions(+), 16 deletions(-)

(limited to 'src/threadpool.c')

diff --git a/src/threadpool.c b/src/threadpool.c
index 681428e..02cd945 100644
--- a/src/threadpool.c
+++ b/src/threadpool.c
@@ -1,3 +1,14 @@
+/**
+ * @file threadpool.c
+ * @author syxhe (https://t.me/syxhe)
+ * @brief *Implementing `threadpool.h`*
+ * @version 0.1
+ * @date 2025-06-09
+ * 
+ * @copyright Copyright (c) 2025
+ * 
+ */
+
 #include "threadpool.h"
 
 #include <threads.h>
@@ -5,32 +16,48 @@
 #include <errno.h>
 #include <error.h>
 
+/**
+ * @brief A generic task - A function, data for that function, and a way to free the data
+ * 
+ */
 typedef struct task {
-    gcallback callback;
-    fcallback freecb;
-    void *data;
+    gcallback callback; //!< A generic callback to be ran when executing the task
+    fcallback freecb;   //!< A free()-like callback to deal with the data
+    void *data;         //!< Some generic data for the generic callback
 } task;
 
+/**
+ * @brief An internal structure used for the `taskqueue`. Analogous to a doubly-linked list's internal node
+ * 
+ */
 typedef struct tqnode {
-    struct tqnode *next;
-    struct tqnode *prev;
-    task *task;
+    struct tqnode *next;    //!< The next element in the `taskqueue`
+    struct tqnode *prev;    //!< The previous element in the `taskqueue`
+    task *task;             //!< The current element's `task`
 } tqnode;
 
+/**
+ * @brief A FIFO queue of tasks
+ * 
+ */
 typedef struct taskqueue {
-    tqnode *start;
-    tqnode *end;
-    unsigned int size;
+    tqnode *start;      //!< The first element of the queue
+    tqnode *end;        //!< The final element of the queue
+    unsigned int size;  //!< The number of elements in the queue
 } taskqueue;
 
+/**
+ * @brief A `taskqueue` built for concurrent access. Essentially a threadpool
+ * 
+ */
 typedef struct ctqueue {
-    mtx_t mutex;
-    cnd_t cond;
-    unsigned char canceled;
+    mtx_t mutex;            //!< A mutex for locking sensitive resources
+    cnd_t cond;             //!< A conditional for waiting on / sending a signal
+    unsigned char canceled; //!< Whether the threads are currently canceled or not
 
-    taskqueue *tq;
-    thrd_t *thrdarr;
-    int talen;
+    taskqueue *tq;          //!< A taskqueue to be accessed concurrently
+    thrd_t *thrdarr;        //!< An array of threads to be dispatched as consumers
+    int talen;              //!< The length of the thread array
 } ctqueue;
 
 
@@ -221,7 +248,7 @@ int taskqueue_size(taskqueue *tq) {
 
 
 
-// Internal helper macro for ctq functions. Acquires a lock via the ctq's mutex, checks to see if the queue has been canceled, then executes "code" as written
+//! Internal helper macro for ctq functions. Acquires a lock via the ctq's mutex, checks to see if the queue has been canceled, then executes "code" as written
 #define __CTQ_INLOCK(ctq, retval, code) do {\
     mtx_lock(&(ctq)->mutex); \
     if((ctq)->canceled) { \
@@ -356,6 +383,7 @@ task * ctqueue_waitpop(ctqueue *ctq) {
     return retval;
 }
 
+//! Simple consumer for eating and executing tasks from the ctq
 static int __CTQ_CONSUMER(void *ctq) {
     if(!ctq) {errno = EINVAL; thrd_exit(-1);}
     ctqueue *real = (ctqueue *)ctq; 
-- 
cgit v1.2.3