From 1444c72db8505340c0988ea286a29bc261297933 Mon Sep 17 00:00:00 2001 From: "@syxhe" Date: Mon, 9 Jun 2025 17:43:50 -0500 Subject: We do a little documentation --- .Doxyfile | 2 +- Makefile | 3 +- src/Makefile | 1 - src/encryption.c | 11 +++++ src/encryption.h | 11 +++++ src/main.c | 13 ++++- src/shared.c | 13 ++++- src/shared.h | 143 ++++++++++++++++++++++++++++++++++++++++++++++++------- src/threadpool.c | 60 ++++++++++++++++------- src/threadpool.h | 11 +++++ 10 files changed, 227 insertions(+), 41 deletions(-) diff --git a/.Doxyfile b/.Doxyfile index 99afbb0..a8d4737 100644 --- a/.Doxyfile +++ b/.Doxyfile @@ -1140,7 +1140,7 @@ SOURCE_TOOLTIPS = YES # The default value is: NO. # This tag requires that the tag SOURCE_BROWSER is set to YES. -USE_HTAGS = YES +USE_HTAGS = NO # If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a # verbatim copy of the header file for each class for which an include is diff --git a/Makefile b/Makefile index 981bb37..815e5b0 100644 --- a/Makefile +++ b/Makefile @@ -1,8 +1,7 @@ -GTAGFILES := $(patsubst %,./src/%,GPATH GRTAGS GTAGS) .PHONY: docs c clean docs: doxygen .Doxyfile c clean: - rm -rvf docs $(GTAGFILES) \ No newline at end of file + rm -rvf docs \ No newline at end of file diff --git a/src/Makefile b/src/Makefile index ff75a8a..0ee5897 100644 --- a/src/Makefile +++ b/src/Makefile @@ -35,7 +35,6 @@ include $(wildcard $(DEPS)) c clean: @-rm -rv main $(OBJECTS) $(DEPS) $(wildcard *.test*) $(wildcard *.enc) - $(MAKE) -C ../ clean val: $(MAKE) all diff --git a/src/encryption.c b/src/encryption.c index 89448e8..fd42929 100644 --- a/src/encryption.c +++ b/src/encryption.c @@ -1,3 +1,14 @@ +/** + * @file encryption.c + * @author syxhe (https://t.me/syxhe) + * @brief *Implementing `encryption.h`* + * @version 0.1 + * @date 2025-06-09 + * + * @copyright Copyright (c) 2025 + * + */ + // TODO: Go back and make sure every function has proper error handling // Oh fucking christ what have I done // I need to make sure every single function in this file returns with an indicated error instead of nuking the whole program with diff --git a/src/encryption.h b/src/encryption.h index f6c018c..5c6a08c 100644 --- a/src/encryption.h +++ b/src/encryption.h @@ -1,3 +1,14 @@ +/** + * @file encryption.h + * @author syxhe (https://t.me/syxhe) + * @brief A collection of all encryption related functions + * @version 0.1 + * @date 2025-06-09 + * + * @copyright Copyright (c) 2025 + * + */ + #ifndef __VXGG_REWRITE___ENCRYPTION_H___1481879318188___ #define __VXGG_REWRITE___ENCRYPTION_H___1481879318188___ diff --git a/src/main.c b/src/main.c index 4b9968c..a95e8d1 100755 --- a/src/main.c +++ b/src/main.c @@ -1,7 +1,16 @@ -#include "shared.h" +/** + * @file main.c + * @author syxhe (https://t.me/syxhe) + * @brief Putting everything together + * @version 0.1 + * @date 2025-06-09 + * + * @copyright Copyright (c) 2025 + * + */ +#include "shared.h" #include "encryption.h" -#include "scanner.h" #include "threadpool.h" #include diff --git a/src/shared.c b/src/shared.c index c02414b..40732f0 100644 --- a/src/shared.c +++ b/src/shared.c @@ -1,3 +1,14 @@ +/** + * @file shared.c + * @author syxhe (https://t.me/syxhe) + * @brief *Implementing `shared.h`* + * @version 0.1 + * @date 2025-06-09 + * + * @copyright Copyright (c) 2025 + * + */ + #include "shared.h" #include @@ -201,7 +212,6 @@ int cleanup_init(cleanup *loc, fcallback callbacks[], void *arguments[], int siz return 0; } -// registers if flag is NOT set int cleanup_register(cleanup *loc, fcallback cb, void *arg) { if(!loc || !cb) ERRRET(EINVAL, -1); if(loc->used >= loc->size || loc->used < 0) ERRRET(ENOMEM, -1); @@ -213,6 +223,7 @@ int cleanup_register(cleanup *loc, fcallback cb, void *arg) { return 0; } +// registers if flag is NOT set int cleanup_cndregister(cleanup *loc, fcallback cb, void *arg, unsigned char flag) { if(flag) return 0; return cleanup_register(loc, cb, arg); diff --git a/src/shared.h b/src/shared.h index 3ff7b2d..6276281 100644 --- a/src/shared.h +++ b/src/shared.h @@ -1,28 +1,41 @@ +/** + * @file shared.h + * @author syxhe (https://t.me/syxhe) + * @brief A collection of functions and macros shared between files, or without a better place + * @version 0.1 + * @date 2025-06-09 + * + * @copyright Copyright (c) 2025 + * + */ + #ifndef __VXGG_REWRITE___SHARED_H___3880294315821___ #define __VXGG_REWRITE___SHARED_H___3880294315821___ 1 #include -typedef int (*gcallback)(void*); // Generic callback signature -typedef void (*fcallback)(void*); // free()-like callback signature +typedef int (*gcallback)(void*); //!< Generic callback signature +typedef void (*fcallback)(void*); //!< free()-like callback signature +//! Get the size of a statically/vla defined array. Doesn't work on arrays allocated via `malloc()` #define STATIC_ARRAY_LEN(arr) (sizeof((arr))/sizeof((arr)[0])) +//! Sets errno to `errval`, then returns `retval`. Defined as a macro because it is meant for use inside functions, not as a function itself #define ERRRET(errval, retval) do {\ errno = (errval);\ return (retval);\ } while (0) -// Defines how `x___alloc()` functions should exit. `___VXGG___XALLOC_EXIT_ON_ERROR___ > 0` calls `error()`, and thus functions -// registered with `atexit()` and `on_exit()`. `___VXGG___XALLOC_EXIT_ON_ERROR___ <= 0` calls `abort()` on error. `x___alloc()` -// type functions will ALWAYS 'abort', doing otherwise defeats the purpose of the function type +/// Defines how `x___alloc()` functions should exit. `___VXGG___XALLOC_EXIT_ON_ERROR___ > 0` calls `error()`, and thus functions +/// registered with `atexit()` and `on_exit()`. `___VXGG___XALLOC_EXIT_ON_ERROR___ <= 0` calls `abort()` on error. `x___alloc()` +/// type functions will ALWAYS 'abort', doing otherwise defeats the purpose of the function type #define ___VXGG___XALLOC_EXIT_ON_ERROR___ 1 -// Defines whether vxgg functions that can error print out a short warning of the error when one is encountered. -// `___VXGG___VERBOSE_ERRORS___ > 0` will print diagnostic error messages, and will do nothing otherwise +/// Defines whether vxgg functions that can error print out a short warning of the error when one is encountered. +/// `___VXGG___VERBOSE_ERRORS___ > 0` will print diagnostic error messages, and will do nothing otherwise #define ___VXGG___VERBOSE_ERRORS___ 1 -// Macro to exit on an alloc error instead of doing the terrible nested if statement that was being used previously +//! Macro to exit on an alloc error instead of doing the terrible nested if statement that was being used previously #define XALLOC_EXIT(msg, ...) do {\ if(!___VXGG___XALLOC_EXIT_ON_ERROR___)\ abort();\ @@ -33,37 +46,122 @@ typedef void (*fcallback)(void*); // free()-like callback signature } while (0) +//! Holdover macro because I'm lazy. Used to call either malloc or xmalloc, but the xalloc functions were a bad idea, so I removed them #define VALLOC(nmemb, size) malloc((nmemb) * (size)) -// Error macro that gcc will not complain about +//! 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` +//! 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 + + +/** + * @brief Read the entire contents of a file descriptor into a malloc()'ed buffer + * + * @param str Pointer to a string. Will be replaced with the malloc()'ed string + * @param initsize The initial size of the malloc()'ed string + * @param fd A file descriptor to read from + * @return int Returns the size of the array on success, or -1 on error + * @note The allocated buffer will expand and contract as necessary, but it's recommended to set `initsize` to some value close to or equal to the size of the file being read to reduce the number of resizes + */ int rwbuf(char **str, unsigned long int initsize, int fd); -// Write the entire contents of a buffer into a file descriptor + +/** + * @brief Write the entire contents of a buffer into a file descriptor + * + * @param fd The file descriptor to write to + * @param buf The buffer to write from + * @param len The length of the buffer + * @return int Returns 0 on success, -1 on error + */ int wwbuf(int fd, const unsigned char *buf, int len); -// `dirname()` reimplementation that returns a malloc()'ed string + + + +/** + * @brief `dirname()` reimplementation that returns a malloc()'ed string + * + * @param path The filepath to be inspected + * @return char* Returns a null-terminated string on success, or `null` on error + */ char * vxdirname(const char * const path); -// A locally defined structure designed for easier function cleanup +/** + * @brief A locally defined structure designed for easier function cleanup + * + */ typedef struct cl { - fcallback *callbacks; // Actual Type: fcallback callbacks[] - void * *arguments; // Actual Type: void *arguments[] - int size; - int used; + fcallback *callbacks; //!< An array of free()-like callbacks. Actual Type: fcallback callbacks[] + void * *arguments; //!< An array of void pointers. Actual Type: void *arguments[] + int size; //!< The size of each array + int used; //!< The current number of used elements in each array } cleanup; +/** + * @brief Initialize a cleanup object + * + * @param loc The cleanup object to be initialized + * @param callbacks An array of free()-like callbacks. Must be `size` elements long + * @param arguments An array of void pointers. Must be `size` elements long + * @param size The number of elements the callbacks and arguments array are long + * @return int Returns 0 on success, -1 on error + */ int cleanup_init(cleanup *loc, fcallback callbacks[], void *arguments[], int size); + +/** + * @brief Register a new callback and argument onto a cleanup stack + * + * @param loc The cleanup object to modify + * @param cb A free()-like callback to run + * @param arg A piece of data for the callback to run + * @return int Returns 0 on success, -1 on error + */ int cleanup_register(cleanup *loc, fcallback cb, void *arg); + +/** + * @brief Conditionally register a callback and argument + * + * @param loc The cleanup object to modify + * @param cb A free()-like callback to run + * @param arg A piece of data for the callback to run + * @param flag Whether or not the register should take place. Will not run if `flag` is non-zero + * @return int Returns 0 on success or skip, -1 on error + */ int cleanup_cndregister(cleanup *loc, fcallback cb, void *arg, unsigned char flag); + +/** + * @brief Clear a cleanup object + * @attention Does not free any registered callbacks or arguments, just marks them as available space + * + * @param loc The cleanup object to modify + * @return int Returns 0 on success, -1 on error + */ int cleanup_clear(cleanup *loc); + +/** + * @brief Fires all the registered callbacks and arguments in a cleanup object in FIFO (stack) order + * + * @param loc The cleanup object to fire + * @return int Returns 0 on success, -1 on error + */ int cleanup_fire(cleanup *loc); + +/** + * @brief Conditionally fires a cleanup object + * + * @param loc The cleanup object in question + * @param flag Whether the object should be fired. Will skip firing if non-zero + * @return int Returns 0 on success, -1 on error + */ int cleanup_cndfire(cleanup *loc, unsigned char flag); +/** + * @brief Initializes a set of variables suitable for use in the cleanup macros + * @param size The number of elements long each array should be + */ #define cleanup_CREATE(size) \ cleanup __CLEANUP; \ fcallback __CLEANUP_FUNCS[(size)]; \ @@ -71,14 +169,23 @@ void *__CLEANUP_ARGS[(size)]; \ unsigned char __FLAG = 0; \ cleanup_init(&__CLEANUP, __CLEANUP_FUNCS, __CLEANUP_ARGS, (size)) +//! Register a callback-argument pair using the local cleanup object #define cleanup_REGISTER(cb, arg) cleanup_register(&__CLEANUP, (cb), (arg)) +//! Conditionally register a callback-argument pair using the local cleanup object #define cleanup_CNDREGISTER(cb, arg) cleanup_cndregister(&__CLEANUP, (cb), (arg), __FLAG) +//! Clean the local cleanup object #define cleanup_CLEAR() cleanup_clear(&__CLEANUP) +//! Fire the local cleanup object #define cleanup_FIRE() cleanup_fire(&__CLEANUP) +//! Conditionally fire the local cleanup object #define cleanup_CNDFIRE() cleanup_cndfire(&__CLEANUP, __FLAG) +//! Set the local cleanup flag to a non-zero number #define cleanup_MARK() (__FLAG = 1) +//! Set the local cleanup flag to zero #define cleanup_UNMARK() (__FLAG = 0) +//! Check if the local cleanup flag is non-zero #define cleanup_ERRORFLAGGED (__FLAG != 0) +//! Conditionally execute some `code` if the local cleanup flag has not been marked #define cleanup_CNDEXEC(code) while(!cleanup_ERRORFLAGGED) {code; break;} #endif \ No newline at end of file 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 @@ -5,32 +16,48 @@ #include #include +/** + * @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; diff --git a/src/threadpool.h b/src/threadpool.h index 1d9a537..91c903c 100644 --- a/src/threadpool.h +++ b/src/threadpool.h @@ -1,3 +1,14 @@ +/** + * @file threadpool.h + * @author syxhe (https://t.me/syxhe) + * @brief An implementation of a threadpool using libc threads + * @version 0.1 + * @date 2025-06-09 + * + * @copyright Copyright (c) 2025 + * + */ + #ifndef __VXGG_REWRITE___THREADPOOL_H___193271180830131___ #define __VXGG_REWRITE___THREADPOOL_H___193271180830131___ 1 -- cgit v1.2.3