From 534a492f2c0bcceac52a287b03dc1ff5eb0b0763 Mon Sep 17 00:00:00 2001 From: "@syxhe" Date: Mon, 9 Jun 2025 15:03:19 -0500 Subject: Trim more fat, add some doxygen markup to the threadpool functions --- src/threadpool.h | 131 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 115 insertions(+), 16 deletions(-) (limited to 'src/threadpool.h') 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 -- cgit v1.2.3