diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-12-09 12:01:44 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-12-09 12:01:44 +0300 |
commit | 9e365069afe156f33fadfad9705e1325f894cd54 (patch) | |
tree | 78373044d029feb51f987b45208e0c1a36958625 /source/blender/blenlib/BLI_mempool.h | |
parent | d8b42751625c915113b64f5a2d9c72f19f009fee (diff) |
Cleanup: move public doc-strings into headers for 'blenlib'
- Added space below non doc-string comments to make it clear
these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.
- Minor improvements to doc-strings.
Ref T92709
Diffstat (limited to 'source/blender/blenlib/BLI_mempool.h')
-rw-r--r-- | source/blender/blenlib/BLI_mempool.h | 44 |
1 files changed, 42 insertions, 2 deletions
diff --git a/source/blender/blenlib/BLI_mempool.h b/source/blender/blenlib/BLI_mempool.h index 61b572a4943..d6abae36e00 100644 --- a/source/blender/blenlib/BLI_mempool.h +++ b/source/blender/blenlib/BLI_mempool.h @@ -44,19 +44,52 @@ void *BLI_mempool_alloc(BLI_mempool *pool) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT A ATTR_NONNULL(1); void *BLI_mempool_calloc(BLI_mempool *pool) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT ATTR_RETURNS_NONNULL ATTR_NONNULL(1); +/** + * Free an element from the mempool. + * + * \note doesn't protect against double frees, take care! + */ void BLI_mempool_free(BLI_mempool *pool, void *addr) ATTR_NONNULL(1, 2); +/** + * Empty the pool, as if it were just created. + * + * \param pool: The pool to clear. + * \param totelem_reserve: Optionally reserve how many items should be kept from clearing. + */ void BLI_mempool_clear_ex(BLI_mempool *pool, const int totelem_reserve) ATTR_NONNULL(1); +/** + * Wrap #BLI_mempool_clear_ex with no reserve set. + */ void BLI_mempool_clear(BLI_mempool *pool) ATTR_NONNULL(1); +/** + * Free the mempool its self (and all elements). + */ void BLI_mempool_destroy(BLI_mempool *pool) ATTR_NONNULL(1); int BLI_mempool_len(const BLI_mempool *pool) ATTR_NONNULL(1); void *BLI_mempool_findelem(BLI_mempool *pool, unsigned int index) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1); +/** + * Fill in \a data with pointers to each element of the mempool, + * to create lookup table. + * + * \param pool: Pool to create a table from. + * \param data: array of pointers at least the size of 'pool->totused' + */ void BLI_mempool_as_table(BLI_mempool *pool, void **data) ATTR_NONNULL(1, 2); +/** + * A version of #BLI_mempool_as_table that allocates and returns the data. + */ void **BLI_mempool_as_tableN(BLI_mempool *pool, const char *allocstr) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2); +/** + * Fill in \a data with the contents of the mempool. + */ void BLI_mempool_as_array(BLI_mempool *pool, void *data) ATTR_NONNULL(1, 2); +/** + * A version of #BLI_mempool_as_array that allocates and returns the data. + */ void *BLI_mempool_as_arrayN(BLI_mempool *pool, const char *allocstr) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2); @@ -67,9 +100,10 @@ void BLI_mempool_set_memory_debug(void); /** * Iteration stuff. - * NOTE: this may easy to produce bugs with. + * \note this may easy to produce bugs with. */ -/* private structure */ + +/* Private structure. */ typedef struct BLI_mempool_iter { BLI_mempool *pool; struct BLI_mempool_chunk *curchunk; @@ -89,7 +123,13 @@ enum { BLI_MEMPOOL_ALLOW_ITER = (1 << 0), }; +/** + * Initialize a new mempool iterator, #BLI_MEMPOOL_ALLOW_ITER flag must be set. + */ void BLI_mempool_iternew(BLI_mempool *pool, BLI_mempool_iter *iter) ATTR_NONNULL(); +/** + * Step over the iterator, returning the mempool item or NULL. + */ void *BLI_mempool_iterstep(BLI_mempool_iter *iter) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); #ifdef __cplusplus |