From 07b1289cd4907aa3defe3fc600f3db1dcefcb719 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sun, 23 Oct 2022 12:30:41 -0400 Subject: Split reference documentation up into groups and add global header The "global" header just provides a convenient place to define the group structure of the library. Applications are better off using the individual headers, but this one will work fine if you don't care about build times or precise dependencies. --- include/zix/allocator.h | 2 +- include/zix/attributes.h | 2 +- include/zix/bitset.h | 2 +- include/zix/btree.h | 2 +- include/zix/bump_allocator.h | 10 +++++ include/zix/digest.h | 2 +- include/zix/hash.h | 2 +- include/zix/ring.h | 92 +++++++++++++++++++++----------------------- include/zix/sem.h | 2 +- include/zix/status.h | 4 +- include/zix/thread.h | 2 +- include/zix/tree.h | 2 +- include/zix/zix.h | 61 +++++++++++++++++++++++++++++ 13 files changed, 125 insertions(+), 60 deletions(-) create mode 100644 include/zix/zix.h (limited to 'include/zix') diff --git a/include/zix/allocator.h b/include/zix/allocator.h index 34ee091..97aa71c 100644 --- a/include/zix/allocator.h +++ b/include/zix/allocator.h @@ -12,7 +12,7 @@ ZIX_BEGIN_DECLS /** @defgroup zix_allocator Allocator - @ingroup zix + @ingroup zix_allocation @{ */ diff --git a/include/zix/attributes.h b/include/zix/attributes.h index 9a25f9c..1fe1183 100644 --- a/include/zix/attributes.h +++ b/include/zix/attributes.h @@ -6,7 +6,7 @@ /** @defgroup zix_attributes Attributes - @ingroup zix + @ingroup zix_utilities @{ */ diff --git a/include/zix/bitset.h b/include/zix/bitset.h index dcb1b93..96816c8 100644 --- a/include/zix/bitset.h +++ b/include/zix/bitset.h @@ -13,7 +13,7 @@ /** @defgroup zix_bitset Bitset - @ingroup zix + @ingroup zix_data_structures @{ */ diff --git a/include/zix/btree.h b/include/zix/btree.h index 0658be8..7199dbc 100644 --- a/include/zix/btree.h +++ b/include/zix/btree.h @@ -17,7 +17,7 @@ ZIX_BEGIN_DECLS /** @defgroup zix_btree BTree - @ingroup zix + @ingroup zix_data_structures @{ */ diff --git a/include/zix/bump_allocator.h b/include/zix/bump_allocator.h index bec45c8..c054207 100644 --- a/include/zix/bump_allocator.h +++ b/include/zix/bump_allocator.h @@ -9,6 +9,12 @@ #include +/** + @defgroup bump_allocator Bump Allocator + @ingroup zix_allocation + @{ +*/ + /** A simple bump-pointer allocator that never frees. @@ -50,4 +56,8 @@ ZIX_API ZixBumpAllocator zix_bump_allocator(size_t capacity, void* ZIX_NONNULL buffer); +/** + @} +*/ + #endif // ZIX_BUMP_ALLOCATOR_H diff --git a/include/zix/digest.h b/include/zix/digest.h index 4c15444..4c4fb02 100644 --- a/include/zix/digest.h +++ b/include/zix/digest.h @@ -13,7 +13,7 @@ ZIX_BEGIN_DECLS /** @defgroup zix_digest Digest - @ingroup zix + @ingroup zix_utilities Functions to generate a short "digest" of data with minimal collisions. diff --git a/include/zix/hash.h b/include/zix/hash.h index a5492a6..026662c 100644 --- a/include/zix/hash.h +++ b/include/zix/hash.h @@ -15,7 +15,7 @@ ZIX_BEGIN_DECLS /** @defgroup zix_hash Hash - @ingroup zix + @ingroup zix_data_structures @{ */ diff --git a/include/zix/ring.h b/include/zix/ring.h index ec255a4..17a0e13 100644 --- a/include/zix/ring.h +++ b/include/zix/ring.h @@ -14,7 +14,12 @@ ZIX_BEGIN_DECLS /** @defgroup zix_ring Ring - @ingroup zix + @ingroup zix_data_structures + @{ +*/ + +/** + @defgroup zix_ring_definition Definition @{ */ @@ -26,20 +31,6 @@ ZIX_BEGIN_DECLS */ typedef struct ZixRingImpl ZixRing; -/** - A transaction for writing data in multiple parts. - - The simple zix_ring_write() can be used to write an atomic message that will - immediately be visible to the reader, but transactions allow data to be - written in several chunks before being "committed" and becoming readable. - This can be useful for things like prefixing messages with a header without - needing an allocated buffer to construct the "packet". -*/ -typedef struct { - uint32_t read_head; ///< Read head at the start of the transaction - uint32_t write_head; ///< Write head if the transaction were committed -} ZixRingTransaction; - /** Create a new ring. @@ -78,24 +69,6 @@ ZIX_API void zix_ring_reset(ZixRing* ZIX_NONNULL ring); -/** - Return the number of bytes of space available for reading. - - Reader only. -*/ -ZIX_PURE_API -uint32_t -zix_ring_read_space(const ZixRing* ZIX_NONNULL ring); - -/** - Return the number of bytes of space available for writing. - - Writer only. -*/ -ZIX_PURE_API -uint32_t -zix_ring_write_space(const ZixRing* ZIX_NONNULL ring); - /** Return the capacity (the total write space when empty). @@ -107,37 +80,59 @@ uint32_t zix_ring_capacity(const ZixRing* ZIX_NONNULL ring); /** - Read from the ring without advancing the read head. - - Reader only. + @} + @defgroup zix_ring_read Reading + Functions that may only be called by the read thread. + @{ */ + +/// Return the number of bytes available for reading +ZIX_PURE_API +uint32_t +zix_ring_read_space(const ZixRing* ZIX_NONNULL ring); + +/// Read from the ring without advancing the read head ZIX_API uint32_t zix_ring_peek(ZixRing* ZIX_NONNULL ring, void* ZIX_NONNULL dst, uint32_t size); -/** - Read from the ring and advance the read head. - - Reader only. -*/ +/// Read from the ring and advance the read head ZIX_API uint32_t zix_ring_read(ZixRing* ZIX_NONNULL ring, void* ZIX_NONNULL dst, uint32_t size); -/** - Skip data in the ring (advance read head without reading). - - Reader only. -*/ +/// Advance the read head, ignoring any data ZIX_API uint32_t zix_ring_skip(ZixRing* ZIX_NONNULL ring, uint32_t size); /** - Write data to the ring. + @} + @defgroup zix_ring_write Writing + Functions that may only be called by the write thread. + @{ +*/ - Writer only. +/** + A transaction for writing data in multiple parts. + + The simple zix_ring_write() can be used to write an atomic message that will + immediately be visible to the reader, but transactions allow data to be + written in several chunks before being "committed" and becoming readable. + This can be useful for things like prefixing messages with a header without + needing an allocated buffer to construct the "packet". */ +typedef struct { + uint32_t read_head; ///< Read head at the start of the transaction + uint32_t write_head; ///< Write head if the transaction were committed +} ZixRingTransaction; + +/// Return the number of bytes available for writing +ZIX_PURE_API +uint32_t +zix_ring_write_space(const ZixRing* ZIX_NONNULL ring); + +/// Write data to the ring ZIX_API uint32_t zix_ring_write(ZixRing* ZIX_NONNULL ring, @@ -204,6 +199,7 @@ zix_ring_commit_write(ZixRing* ZIX_NONNULL ring, /** @} + @} */ ZIX_END_DECLS diff --git a/include/zix/sem.h b/include/zix/sem.h index b22dfdd..ea993fb 100644 --- a/include/zix/sem.h +++ b/include/zix/sem.h @@ -21,7 +21,7 @@ ZIX_BEGIN_DECLS /** @defgroup zix_sem Semaphore - @ingroup zix + @ingroup zix_threading @{ */ diff --git a/include/zix/status.h b/include/zix/status.h index 906b812..0e95f43 100644 --- a/include/zix/status.h +++ b/include/zix/status.h @@ -9,9 +9,8 @@ ZIX_BEGIN_DECLS /** - @defgroup zix Zix C API - @{ @defgroup zix_status Status Codes + @ingroup zix_utilities @{ */ @@ -38,7 +37,6 @@ zix_strerror(ZixStatus status); /** @} - @} */ ZIX_END_DECLS diff --git a/include/zix/thread.h b/include/zix/thread.h index 3ba4702..d3b5021 100644 --- a/include/zix/thread.h +++ b/include/zix/thread.h @@ -19,7 +19,7 @@ ZIX_BEGIN_DECLS /** @defgroup zix_thread Thread - @ingroup zix + @ingroup zix_threading @{ */ diff --git a/include/zix/tree.h b/include/zix/tree.h index 919cba9..939385b 100644 --- a/include/zix/tree.h +++ b/include/zix/tree.h @@ -16,7 +16,7 @@ ZIX_BEGIN_DECLS /** @defgroup zix_tree Tree - @ingroup zix + @ingroup zix_data_structures @{ */ diff --git a/include/zix/zix.h b/include/zix/zix.h new file mode 100644 index 0000000..02ab31f --- /dev/null +++ b/include/zix/zix.h @@ -0,0 +1,61 @@ +// Copyright 2016-2022 David Robillard +// SPDX-License-Identifier: ISC + +#ifndef ZIX_ZIX_H +#define ZIX_ZIX_H + +// IWYU pragma: begin_exports + +/** + @defgroup zix Zix C API + @{ +*/ + +/** + @defgroup zix_utilities Utilities + @{ +*/ + +#include "zix/attributes.h" +#include "zix/digest.h" +#include "zix/function_types.h" +#include "zix/status.h" + +/** + @} + @defgroup zix_allocation Allocation + @{ +*/ + +#include "zix/allocator.h" +#include "zix/bump_allocator.h" + +/** + @} + @defgroup zix_data_structures Data Structures + @{ +*/ + +#include "zix/bitset.h" +#include "zix/btree.h" +#include "zix/hash.h" +#include "zix/ring.h" +#include "zix/tree.h" + +/** + @} + @defgroup zix_threading Threading + @{ +*/ + +#include "zix/sem.h" +#include "zix/thread.h" + +/** + @} + @} +*/ + +// IWYU pragma: end_exports + +#endif /* ZIX_ZIX_H */ -- cgit v1.2.1