Add more callbacks for fork() event, doc progress

* Add fork.prepare(), fork.parent() and fork.child() to match with
  pthread_atfork(), which makes more sense
* Code documentation progress

1 files changed, 85 insertions, 4 deletions

diff --git a/src/iobuf.h b/src/iobuf.h
index 7d6233e..9446274 100644
--- a/src/iobuf.h
+++ b/src/iobuf.h
@@ -1,3 +1,9 @@
+/** \file
+ * \brief The IO buffer implementation.
+ * \note The IO buffer is a FIFO byte array object with some extra convenience
+ *	functions. The IO buffer is similar to the C++ counterpart,
+ *	\c std::vector<uint8_t>
+ */
 /*
 * Copyright (c) 2019-2021 David Timber <mieabby@gmail.com>
 *
@@ -27,26 +33,101 @@
 #include <sys/types.h>
 
 
+/* Alias declarations */
 typedef struct prne_iobuf prne_iobuf_t;
 
+// The IO buffer object.
 struct prne_iobuf {
-	uint8_t *m;
-	size_t size;
-	size_t avail;
-	size_t len;
+	uint8_t *m; // The buffer
+	size_t size; // The size of buffer
+	size_t avail; // The length of the buffer available (size - len)
+	size_t len; // The length of the contents
+	/* The ownership status of the buffer.
+	 * True if the object is responsible for freeing the allocated memory for
+	 * the buffer. False otherwise.
+	 */
 	bool ownership;
 };
 
 
+/**
+ * \brief Initialise the IO buffer object.
+ * \param ib The pointer to the IO buffer object.
+ * \note \p ib can be freed using \c prne_free_iobuf() once initialised.
+ * \see \c prne_free_iobuf()
+ */
 void prne_init_iobuf (prne_iobuf_t *ib);
+/**
+ * \brief Free resources allocated for the IO buffer object.
+ * \param ib The pointer to the IO buffer object.
+ * \see \c prne_init_iobuf()
+ */
 void prne_free_iobuf (prne_iobuf_t *ib);
+/**
+ * \brief Allocate memory to set the size of the buffer.
+ * \param ib The pointer to the IO buffer object.
+ * \param ny_size The new byte size of the buffer.
+ * \retval true if allocation has been successful.
+ * \retval false otherwise with \c errno set.
+ */
 bool prne_alloc_iobuf (prne_iobuf_t *ib, const size_t ny_size);
+/**
+ * \brief Try allocating memory for the buffer using the sizes specified in the
+ *	array.
+ * \param ib The pointer to the IO buffer object.
+ * \param ny_size The pointer to the array of new sizes of the buffer.
+ * \retval true if the size of the buffer has been successfully set to one of
+ *	the sizes in \p ny_size.
+ * \retval false otherwise with \c errno set.
+ * \note The sizes are tried from the first element of \p ny_size. Usually,
+ *	you'd want to set the elements of the array in the descending order so the
+ *	largest size is tried first which is optimal in most cases.
+ */
 bool prne_try_alloc_iobuf (prne_iobuf_t *ib, const size_t *ny_size);
+/**
+ * \brief Set up the IO buffer object to use the external buffer, relieving the
+ *	IO buffer object's responsibility of freeing the buffer.
+ * \param ib The pointer to the IO buffer object.
+ * \param m The pointer to the external buffer.
+ * \param size The size of the external buffer.
+ * \param len The initial length of the contents in the external buffer.
+ *	This is usually zero unless there are contents in the external buffer to be
+ *	used.
+ * \note The function is useful when the use of static type of memory such as
+ *	.bss or stack is desired. Any dynamic resource previously allocated is
+*	freed.
+ */
 void prne_iobuf_setextbuf (
 	prne_iobuf_t *ib,
 	uint8_t *m,
 	const size_t size,
 	const size_t len);
+/**
+ * \brief Reset the buffer state - Set \c len to zero and \c avail to the size
+ *	of the buffer.
+ * \param ib The pointer to the io buffer object.
+ * \note Use this function to discard the contents of the buffer. The contents
+ *	of the buffer will remain untouched. You may want to use
+ *	\c prne_iobuf_zero() to scrub the data off memory.
+ * \see \c prne_iobuf_zero()
+ */
 void prne_iobuf_reset (prne_iobuf_t *ib);
+/**
+ * \brief Zero-fill the entire buffer - \c memset() convenience function.
+ * \param ib The pointer to the IO buffer object.
+ * \note This is the equivalent of calling \c memset() and
+ *	\c prne_iobuf_reset().
+ */
 void prne_iobuf_zero (prne_iobuf_t *ib);
+/**
+ * \brief Shift the contents of the buffer - \c memmove() convenience function.
+ * \param ib The pointer to the IO buffer object.
+ * \param amount The number of bytes to shift. A positive value simply increases
+ *	\c len and decreases \c avail. A negative value causes the function to call
+ *	\c memmove() to discard the amount of data specified, increasing \c avail
+ *	and decreasing \c len
+ * \warning When shifting the contents of the buffer to the left, depending on
+ *	the behaviour of \c memmove(), the contents of the buffer on the right may
+ *	remain intact on memory. Do not use IO buffer to store sensitive data.
+ */
 void prne_iobuf_shift (prne_iobuf_t *ib, const ssize_t amount);