From 201152a6d32c41f035629a8aead81c478a09f24e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ren=C3=A9=20Kijewski?= <rene.kijewski@fu-berlin.de>
Date: Sat, 3 May 2014 20:13:20 +0200
Subject: [PATCH] ringbuffer: add documentation
---
sys/include/ringbuffer.h | 76 +++++++++++++++++++++++++++++++++++++---
sys/lib/ringbuffer.c | 14 ++++++++
2 files changed, 86 insertions(+), 4 deletions(-)
diff --git a/sys/include/ringbuffer.h b/sys/include/ringbuffer.h
index 1564fc962c..ad463c478a 100644
--- a/sys/include/ringbuffer.h
+++ b/sys/include/ringbuffer.h
@@ -19,30 +19,98 @@
#ifndef __RINGBUFFER_H
#define __RINGBUFFER_H
+/**
+ * @brief Ringbuffer.
+ * @details Non thread-safe FIFO ringbuffer implementation around a `char` array.
+ */
typedef struct ringbuffer {
- char *buf;
- unsigned int size;
- unsigned int start;
- unsigned int avail;
+ char *buf; /**< Buffer to operate on. */
+ unsigned int size; /**< Size of buf. */
+ unsigned int start; /**< Current read position in the ring buffer. */
+ unsigned int avail; /**< Number of elements available for reading. */
} ringbuffer_t;
+/**
+ * @brief Initialize a ringbuffer.
+ * @param[out] rb Datum to initialize.
+ * @param[in] buffer Buffer to use by rb.
+ * @param[in] bufsize `sizeof (buffer)`
+ */
void ringbuffer_init(ringbuffer_t *restrict rb, char *buffer, unsigned bufsize);
+
+/**
+ * @brief Add an element to the ringbuffer.
+ * @details If rb is full, then the oldest element gets overwritten.
+ * Test ringbuffer_full() first if overwriting is not intended.
+ * @param[in,out] rb Ringbuffer to operate on.
+ * @param[in] c Element to add.
+ * @returns The element that was dropped, iff the buffer was full.
+ * -1 iff the buffer was not full.
+ */
int ringbuffer_add_one(ringbuffer_t *restrict rb, char c);
+
+/**
+ * @brief Add a number of elements to the ringbuffer.
+ * @details Only so many elements are added as fit in the ringbuffer.
+ * No elements get overwritten.
+ * If this is not the intended behavior, then use ringbuffer_add_one() in a loop instead.
+ * @param[in,out] rb Ringbuffer to operate on.
+ * @param[in] buf Buffer to add elements from.
+ * @param[in] n Maximum number of elements to add.
+ * @returns Number of elements actually added. 0 if rb is full.
+ */
unsigned ringbuffer_add(ringbuffer_t *restrict rb, const char *buf, unsigned n);
+
+/**
+ * @brief Peek and remove oldest element from the ringbuffer.
+ * @param[in,out] rb Ringbuffer to operate on.
+ * @returns The oldest element that was added, or `-1` if rb is empty.
+ */
int ringbuffer_get_one(ringbuffer_t *restrict rb);
+
+/**
+ * @brief Read and remove a number of elements from the ringbuffer.
+ * @param[in,out] rb Ringbuffer to operate on.
+ * @param[out] buf Buffer to write into.
+ * @param[in] n Read at most n elements.
+ * @returns Number of elements actually read.
+ */
unsigned ringbuffer_get(ringbuffer_t *restrict rb, char *buf, unsigned n);
+/**
+ * @brief Test if the ringbuffer is empty.
+ * @param[in,out] rb Ringbuffer to operate on.
+ * @returns 0 iff not empty
+ */
static inline int ringbuffer_empty(const ringbuffer_t *restrict rb)
{
return rb->avail == 0;
}
+/**
+ * @brief Test if the ringbuffer is full.
+ * @param[in,out] rb Ringbuffer to operate on.
+ * @returns 0 iff not full
+ */
static inline int ringbuffer_full(const ringbuffer_t *restrict rb)
{
return rb->avail == rb->size;
}
+/**
+ * @brief Read, but don't remove, the oldest element in the buffer.
+ * @param[in] rb Ringbuffer to operate on.
+ * @returns Same as ringbuffer_get_one()
+ */
int ringbuffer_peek_one(const ringbuffer_t *restrict rb);
+
+/**
+ * @brief Read, but don't remove, the a number of element of the buffer.
+ * @param[in] rb Ringbuffer to operate on.
+ * @param[out] buf Buffer to write into.
+ * @param[in] n Read at most n elements.
+ * @returns Same as ringbuffer_get()
+ */
unsigned ringbuffer_peek(const ringbuffer_t *restrict rb, char *buf, unsigned n);
#endif /* __RINGBUFFER_H */
diff --git a/sys/lib/ringbuffer.c b/sys/lib/ringbuffer.c
index 084ae48f24..be2263a329 100644
--- a/sys/lib/ringbuffer.c
+++ b/sys/lib/ringbuffer.c
@@ -26,6 +26,13 @@ void ringbuffer_init(ringbuffer_t *restrict rb, char *buffer, unsigned bufsize)
rb->avail = 0;
}
+/**
+ * @brief Add an element to the end of the ringbuffer.
+ * @details This helper function does not check the pre-requirements for adding,
+ * i.e. the caller has to ensure that ringbuffer_full() is false.
+ * @param[in,out] rb Ringbuffer to operate on.
+ * @param[in] c Element to add.
+ */
static void add_tail(ringbuffer_t *restrict rb, char c)
{
unsigned pos = rb->start + rb->avail++;
@@ -35,6 +42,13 @@ static void add_tail(ringbuffer_t *restrict rb, char c)
rb->buf[pos] = c;
}
+/**
+ * @brief Remove an element from the start of the ringbuffer.
+ * @details This helper function does not check the pre-requirements for reading,
+ * i.e. the caller has to ensure that ringbuffer_empty() is false.
+ * @param[in,out] rb Ringbuffer to operate on.
+ * @returns The removed element.
+ */
static char get_head(ringbuffer_t *restrict rb)
{
char result = rb->buf[rb->start];
--
GitLab