summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2022-10-23 12:30:41 -0400
committerDavid Robillard <d@drobilla.net>2022-10-23 12:40:05 -0400
commit07b1289cd4907aa3defe3fc600f3db1dcefcb719 (patch)
treeffc16da1673cf0d1b7a4980e5b63215dd2143647
parentaeb1b45effb1eb64761a140544a38ad60c868228 (diff)
downloadzix-07b1289cd4907aa3defe3fc600f3db1dcefcb719.tar.gz
zix-07b1289cd4907aa3defe3fc600f3db1dcefcb719.tar.bz2
zix-07b1289cd4907aa3defe3fc600f3db1dcefcb719.zip
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.
-rw-r--r--include/zix/allocator.h2
-rw-r--r--include/zix/attributes.h2
-rw-r--r--include/zix/bitset.h2
-rw-r--r--include/zix/btree.h2
-rw-r--r--include/zix/bump_allocator.h10
-rw-r--r--include/zix/digest.h2
-rw-r--r--include/zix/hash.h2
-rw-r--r--include/zix/ring.h92
-rw-r--r--include/zix/sem.h2
-rw-r--r--include/zix/status.h4
-rw-r--r--include/zix/thread.h2
-rw-r--r--include/zix/tree.h2
-rw-r--r--include/zix/zix.h61
-rw-r--r--meson.build1
-rw-r--r--test/headers/test_headers.c1
15 files changed, 127 insertions, 60 deletions
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
@@ -10,6 +10,12 @@
#include <stddef.h>
/**
+ @defgroup bump_allocator Bump Allocator
+ @ingroup zix_allocation
+ @{
+*/
+
+/**
A simple bump-pointer allocator that never frees.
This is about the simplest possible allocator that is useful in practice.
@@ -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
@{
*/
@@ -27,20 +32,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.
@param allocator Allocator for the ring.
@@ -79,24 +70,6 @@ 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).
This function returns a constant for any given ring, and may (but usually
@@ -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 <d@drobilla.net>
+// 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 */
diff --git a/meson.build b/meson.build
index 8e515f3..58669cf 100644
--- a/meson.build
+++ b/meson.build
@@ -105,6 +105,7 @@ c_headers = files(
'include/zix/status.h',
'include/zix/thread.h',
'include/zix/tree.h',
+ 'include/zix/zix.h',
)
sources = files(
diff --git a/test/headers/test_headers.c b/test/headers/test_headers.c
index 80a1852..c1a9fc3 100644
--- a/test/headers/test_headers.c
+++ b/test/headers/test_headers.c
@@ -14,6 +14,7 @@
#include "zix/status.h" // IWYU pragma: keep
#include "zix/thread.h" // IWYU pragma: keep
#include "zix/tree.h" // IWYU pragma: keep
+#include "zix/zix.h" // IWYU pragma: keep
#if defined(__GNUC__)
__attribute__((const))