diff --git a/libluna/include/luna/CPath.h b/libluna/include/luna/CPath.h index c1fad9fe..22fd9e58 100644 --- a/libluna/include/luna/CPath.h +++ b/libluna/include/luna/CPath.h @@ -1,7 +1,29 @@ +/** + * @file CPath.h + * @author apio (cloudapio.eu) + * @brief Basic operations on paths using C-style strings. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #pragma once extern "C" { - char* basename(char*); - char* dirname(char*); + /** + * @brief Get the base name of a path. + * + * @param path The path to use. This will be modified. + * @return char* A pointer to the base name (usually points inside path). + */ + char* basename(char* path); + + /** + * @brief Get the parent directory of a path. + * + * @param path The path to use. This will be modified. + * @return char* A pointer to the directory (usually points inside path). + */ + char* dirname(char* path); } diff --git a/libluna/include/luna/CRC32.h b/libluna/include/luna/CRC32.h index 4e4c033e..582ca665 100644 --- a/libluna/include/luna/CRC32.h +++ b/libluna/include/luna/CRC32.h @@ -1,11 +1,34 @@ +/** + * @file CRC32.h + * @author apio (cloudapio.eu) + * @brief CRC32 checksum calculation. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #pragma once #include +/** + * @brief A class to calculate a CRC32 checksum. + */ class CRC32 { public: + /** + * @brief Add data to the checksum. + * + * @param data The data to add. + * @param size The amount of bytes to add. + */ void append(const u8* data, usize size); + /** + * @brief Calculate the final checksum. + * + * @return u32 The calculated checksum. + */ u32 digest(); private: diff --git a/libluna/include/luna/CircularQueue.h b/libluna/include/luna/CircularQueue.h index 50317feb..a4265cce 100644 --- a/libluna/include/luna/CircularQueue.h +++ b/libluna/include/luna/CircularQueue.h @@ -1,9 +1,24 @@ +/** + * @file CircularQueue.h + * @author apio (cloudapio.eu) + * @brief Lock-free FIFO data structures. + * + * @copyright Copyright (c) 2022-2023, the Luna authors. + * + */ + #pragma once #include #include #include #include +/** + * @brief An atomic lock-free circular FIFO queue. + * + * @tparam T The type of data to store in this queue. + * @tparam Size The amount of elements to make space for. + */ template class CircularQueue { enum @@ -16,11 +31,24 @@ template class CircularQueue { } + /** + * @brief Return whether the queue is empty. + * + * @return true The queue is empty. + * @return false The queue is not empty. + */ bool is_empty() { return m_tail.load() == m_head.load(); } + /** + * @brief Push a value onto the queue. + * + * @param value The value to push. + * @return true The operation succeded. + * @return false The queue was full or someone else was trying to push a value at the same time. + */ bool try_push(const T& value) { usize current_tail = m_tail.load(MemoryOrder::Relaxed); @@ -39,6 +67,13 @@ template class CircularQueue return true; } + /** + * @brief Pop a value from the queue. + * + * @param value The variable to store the value into. + * @return true The operation succeded. + * @return false The queue was empty or someone else was trying to pop a value at the same time. + */ bool try_pop(T& value) { usize current_head = m_head.load(MemoryOrder::Relaxed); @@ -63,6 +98,13 @@ template class CircularQueue Atomic m_tail = 0; }; +/** + * @brief An atomic lock-free circular FIFO queue. + * + * In this variant the size is set at runtime. + * + * @tparam T The type of data to store in this queue. + */ template class DynamicCircularQueue { @@ -76,18 +118,41 @@ template class DynamicCircularQueue if (m_data) free_impl(m_data); } + /** + * @brief Return whether the queue is empty. + * + * @return true The queue is empty. + * @return false The queue is not empty. + */ bool is_empty() { return m_tail.load() == m_head.load(); } + /** + * @brief Set the size of the queue and allocate memory for it. + * + * This should not be used to grow the queue, as all existing data is lost. In most cases, this function will only + * be called once to set the initial size of the queue and that's it. + * + * @param size The amount of elements to make space for. + * @return Result Whether the operation succeded. + */ Result set_size(usize size) { + if (m_data) free_impl(m_data); m_data = (T*)TRY(calloc_impl(size + 1, sizeof(T), false)); m_capacity = size + 1; return {}; } + /** + * @brief Push a value onto the queue. + * + * @param value The value to push. + * @return true The operation succeded. + * @return false The queue was full or someone else was trying to push a value at the same time. + */ bool try_push(const T& value) { check(m_capacity); @@ -107,6 +172,13 @@ template class DynamicCircularQueue return true; } + /** + * @brief Pop a value from the queue. + * + * @param value The variable to store the value into. + * @return true The operation succeded. + * @return false The queue was empty or someone else was trying to pop a value at the same time. + */ bool try_pop(T& value) { check(m_capacity); diff --git a/libluna/src/CPath.cpp b/libluna/src/CPath.cpp index 4a503fe7..883d9c09 100644 --- a/libluna/src/CPath.cpp +++ b/libluna/src/CPath.cpp @@ -1,3 +1,12 @@ +/** + * @file CPath.cpp + * @author apio (cloudapio.eu) + * @brief Basic operations on paths using C-style strings. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #include #include diff --git a/libluna/src/CRC32.cpp b/libluna/src/CRC32.cpp index 66594c74..ff84924f 100644 --- a/libluna/src/CRC32.cpp +++ b/libluna/src/CRC32.cpp @@ -1,5 +1,13 @@ +/** + * @file CRC32.cpp + * @author apio (cloudapio.eu) + * @brief CRC32 checksum calculation. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #include -#include static const u32 crc_table[] = { 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832,