diff options
| -rw-r--r-- | doc/allocation.rst | 24 | ||||
| -rw-r--r-- | doc/error_handling.rst | 13 | ||||
| -rw-r--r-- | doc/meson.build | 2 | ||||
| -rw-r--r-- | doc/using_zix.rst | 2 | ||||
| -rw-r--r-- | include/zix/allocator.h | 2 | ||||
| -rw-r--r-- | include/zix/bitset.h | 66 | ||||
| -rw-r--r-- | include/zix/bump_allocator.h | 2 | ||||
| -rw-r--r-- | include/zix/ring.h | 5 | ||||
| -rw-r--r-- | include/zix/sem.h | 4 |
9 files changed, 105 insertions, 15 deletions
diff --git a/doc/allocation.rst b/doc/allocation.rst new file mode 100644 index 0000000..5b9d507 --- /dev/null +++ b/doc/allocation.rst @@ -0,0 +1,24 @@ +.. + Copyright 2022 David Robillard <d@drobilla.net> + SPDX-License-Identifier: ISC + +Allocation +========== + +.. default-domain:: c +.. highlight:: c + +Functions or objects that allocate memory take a pointer to a :struct:`ZixAllocator`, +which can be used to customize the allocation scheme. +To simply use the system allocator, +callers can pass ``NULL``, +which is equivalent to :func:`zix_default_allocator()`. + +Zix includes one implementation of a custom allocator, +a very simple bump-pointer allocator which can be created with :func:`zix_bump_allocator`. + +A convenience API for using a custom allocator if provided +(and the system allocator otherwise) +is provided with functions like :func:`zix_malloc` that correspond to those in the standard C API. + +Memory allocated with an allocator must be freed by calling :func:`zix_free` with the same allocator. diff --git a/doc/error_handling.rst b/doc/error_handling.rst new file mode 100644 index 0000000..331aa33 --- /dev/null +++ b/doc/error_handling.rst @@ -0,0 +1,13 @@ +.. + Copyright 2022 David Robillard <d@drobilla.net> + SPDX-License-Identifier: ISC + +Error Handling +============== + +.. default-domain:: c +.. highlight:: c + +Most functions return a :enum:`ZixStatus` which describes whether they succeeded (with zero, or :enumerator:`ZIX_STATUS_SUCCESS`) +or why they failed. +The human-readable message for a status can be retrieved with :func:`zix_strerror`. diff --git a/doc/meson.build b/doc/meson.build index e9d3b52..d0f1952 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -28,6 +28,8 @@ if build_docs # Generated API Reference c_rst_files = files( + 'allocation.rst', + 'error_handling.rst', 'index.rst', 'string_views.rst', 'summary.rst', diff --git a/doc/using_zix.rst b/doc/using_zix.rst index f97ecf0..018140b 100644 --- a/doc/using_zix.rst +++ b/doc/using_zix.rst @@ -8,5 +8,7 @@ Using Zix .. toctree:: + error_handling string_views + allocation diff --git a/include/zix/allocator.h b/include/zix/allocator.h index 97aa71c..5ab8bf8 100644 --- a/include/zix/allocator.h +++ b/include/zix/allocator.h @@ -87,7 +87,7 @@ typedef void* ZIX_ALLOCATED (*ZixAlignedAllocFunc)( // This works like the standard C free(), but must be used to free memory allocated with the aligned_alloc() method of the allocator. This allows - portability to systems (like Windows) that can not use the same free function + portability to systems (like Windows) that can't use the same free function in these cases. */ typedef void (*ZixAlignedFreeFunc)( // diff --git a/include/zix/bitset.h b/include/zix/bitset.h index 96816c8..491346d 100644 --- a/include/zix/bitset.h +++ b/include/zix/bitset.h @@ -17,10 +17,21 @@ @{ */ -/// A bitset (always referred to by pointer, actually an array) +/** + A bitset element. + + A bitset is an array that is always referred to by pointer. This type is + the type of an element of that array (which stores some number of bits), so + a pointer to this type is a pointer to a bitset. +*/ typedef unsigned long ZixBitset; -/// Tally of the number of bits in one ZixBitset element +/** + Tally of the number of bits in one ZixBitset element. + + Like #ZixBitset, this is the type of one element of a tally, which is a + parallel array to the bitset one, also always referred to by pointer. +*/ typedef uint8_t ZixBitsetTally; /// The number of bits per ZixBitset array element @@ -31,33 +42,66 @@ typedef uint8_t ZixBitsetTally; (((n_bits) / ZIX_BITSET_BITS_PER_ELEM) + \ (((n_bits) % ZIX_BITSET_BITS_PER_ELEM) ? 1 : 0)) -/// Clear a Bitset +/** + Clear a bitset. + + @param b The bitset to clear. + @param t The tally for `b` to update. + @param n_bits The number of bits in `b`. +*/ ZIX_API void zix_bitset_clear(ZixBitset* ZIX_NONNULL b, ZixBitsetTally* ZIX_NONNULL t, size_t n_bits); -/// Set bit `i` in `t` to 1 +/** + Set bit `i` in `b`. + + @param b The bitset to set bit `i` in. + @param t The tally for `b` to update. + @param i The index of the bit to set. +*/ ZIX_API void zix_bitset_set(ZixBitset* ZIX_NONNULL b, ZixBitsetTally* ZIX_NONNULL t, size_t i); -/// Clear bit `i` in `t` (set to 0) +/** + Clear bit `i` in `b`. + + @param b The bitset to set bit `i` in. + @param t The tally for `b` to update. + @param i The index of the bit to set. +*/ ZIX_API void zix_bitset_reset(ZixBitset* ZIX_NONNULL b, ZixBitsetTally* ZIX_NONNULL t, size_t i); -/// Return the bit at index `i` in `b` +/** + Return the bit at index `i` in `b`. + + @param b The bitset to access. + @param i The index of the bit to return. + @return True if the bit is set (1), false otherwise (0). +*/ ZIX_PURE_API bool zix_bitset_get(const ZixBitset* ZIX_NONNULL b, size_t i); -/// Return the number of set bits in `b` up to bit `i` (non-inclusive) +/** + Return the number of set bits in `b` up to bit `i`. + + The returned count is non-inclusive, that is, doesn't include bit `i`. + + @param b The bitset to count. + @param t The tally for `b`. + @param i The end index to stop counting at. + @return The number of set bits in `b` from bit 0 to bit `i - 1`. +*/ ZIX_PURE_API size_t zix_bitset_count_up_to(const ZixBitset* ZIX_NONNULL b, @@ -65,8 +109,12 @@ zix_bitset_count_up_to(const ZixBitset* ZIX_NONNULL b, size_t i); /** - Return the number of set bits in `b` up to bit `i` (non-inclusive) if bit - `i` is set, or `(size_t)-1` otherwise. + Return the number of set bits in `b` up to bit `i` if it is set. + + The returned count is non-inclusive, that is, doesn't include bit `i`. + + @return The number of set bits in `b` from bit 0 to bit `i - 1` if bit `i` + is set, otherwise, `(size_t)-1`. */ ZIX_PURE_API size_t diff --git a/include/zix/bump_allocator.h b/include/zix/bump_allocator.h index c054207..c69de92 100644 --- a/include/zix/bump_allocator.h +++ b/include/zix/bump_allocator.h @@ -37,7 +37,7 @@ pointer, essentially serving as a cheap pop and pop-push, respectively. - Calling free() means that realloc() will fail and free() will do nothing - until the next allocation. In other words, free() can not be used twice + until the next allocation. In other words, free() can't be used twice in a row. - There is no relocation: realloc() always returns either the input pointer, diff --git a/include/zix/ring.h b/include/zix/ring.h index 04c3bda..181a7a3 100644 --- a/include/zix/ring.h +++ b/include/zix/ring.h @@ -34,8 +34,9 @@ typedef struct ZixRingImpl ZixRing; /** Create a new ring. - @param allocator Allocator for the ring. - @param size Size in bytes (note this may be rounded up). + @param allocator Allocator for the ring object and its array. + + @param size Size of the ring in bytes (note this may be rounded up). At most `size` - 1 bytes may be stored in the ring at once. */ diff --git a/include/zix/sem.h b/include/zix/sem.h index ea993fb..206e4e9 100644 --- a/include/zix/sem.h +++ b/include/zix/sem.h @@ -31,8 +31,8 @@ struct ZixSemImpl; A counting semaphore. This is an integer that is never negative, and has two main operations: - increment (post) and decrement (wait). If a decrement can not be performed - (i.e. the value is 0) the caller will be blocked until another thread posts + increment (post) and decrement (wait). If a decrement can't be performed + (because the value is 0) the caller will be blocked until another thread posts and the operation can succeed. Semaphores can be created with any starting value, but typically this will |