Mercurial > hg > webserver / file diff

--- a/src/ucx/cx/buffer.h	Sat Mar 25 17:18:51 2023 +0100
+++ b/src/ucx/cx/buffer.h	Fri May 05 18:02:11 2023 +0200
@@ -149,11 +149,12 @@
  * @param space pointer to the memory area, or \c NULL to allocate
  * new memory
  * @param capacity the capacity of the buffer
- * @param allocator the allocator this buffer shall use for automatic memory management
+ * @param allocator the allocator this buffer shall use for automatic
+ * memory management. If \c NULL, the default heap allocator will be used.
  * @param flags buffer features (see cx_buffer_s.flags)
  * @return zero on success, non-zero if a required allocation failed
  */
-__attribute__((__nonnull__(1, 4)))
+__attribute__((__nonnull__(1)))
 int cxBufferInit(
         CxBuffer *buffer,
         void *space,
@@ -163,16 +164,52 @@
 );
 
 /**
+ * Allocates and initializes a fresh buffer.
+ *
+ * \note You may provide \c NULL as argument for \p space.
+ * Then this function will allocate the space and enforce
+ * the #CX_BUFFER_FREE_CONTENTS flag.
+ *
+ * @param space pointer to the memory area, or \c NULL to allocate
+ * new memory
+ * @param capacity the capacity of the buffer
+ * @param allocator the allocator to use for allocating the structure and the automatic
+ * memory management within the buffer. If \c NULL, the default heap allocator will be used.
+ * @param flags buffer features (see cx_buffer_s.flags)
+ * @return a pointer to the buffer on success, \c NULL if a required allocation failed
+ */
+CxBuffer *cxBufferCreate(
+        void *space,
+        size_t capacity,
+        CxAllocator const *allocator,
+        int flags
+);
+
+/**
  * Destroys the buffer contents.
  *
  * Has no effect if the #CX_BUFFER_FREE_CONTENTS feature is not enabled.
+ * If you want to free the memory of the entire buffer, use cxBufferFree().
  *
  * @param buffer the buffer which contents shall be destroyed
+ * @see cxBufferInit()
  */
 __attribute__((__nonnull__))
 void cxBufferDestroy(CxBuffer *buffer);
 
 /**
+ * Deallocates the buffer.
+ *
+ * If the #CX_BUFFER_FREE_CONTENTS feature is enabled, this function also destroys
+ * the contents. If you \em only want to destroy the contents, use cxBufferDestroy().
+ *
+ * @param buffer the buffer to deallocate
+ * @see cxBufferCreate()
+ */
+__attribute__((__nonnull__))
+void cxBufferFree(CxBuffer *buffer);
+
+/**
  * Shifts the contents of the buffer by the given offset.
  *
  * If the offset is positive, the contents are shifted to the right.