Merge pull request 'SimpleRingBuffer Improvements' (#172) from KSat/fsfw:mueller/SimpleRingBufferUpdate2 into master

Reviewed-on: fsfw/fsfw#172

container/RingBufferBase.h

@@ -1,96 +1,113 @@
-#ifndef FRAMEWORK_CONTAINER_RINGBUFFERBASE_H_
+#ifndef FSFW_CONTAINER_RINGBUFFERBASE_H_
-#define FRAMEWORK_CONTAINER_RINGBUFFERBASE_H_
+#define FSFW_CONTAINER_RINGBUFFERBASE_H_
 
 #include "../returnvalues/HasReturnvaluesIF.h"
+#include <cstddef>
 
 template<uint8_t N_READ_PTRS = 1>
 class RingBufferBase {
 public:
-	RingBufferBase(uint32_t startAddress, uint32_t size, bool overwriteOld) :
+	RingBufferBase(size_t startAddress, const size_t size, bool overwriteOld) :
-			start(startAddress), write(startAddress), size(size), overwriteOld(overwriteOld) {
+			start(startAddress), write(startAddress), size(size),
+			overwriteOld(overwriteOld) {
 		for (uint8_t count = 0; count < N_READ_PTRS; count++) {
 			read[count] = startAddress;
 		}
 	}
-	ReturnValue_t readData(uint32_t amount, uint8_t n = 0) {
+
-		if (availableReadData(n) >= amount) {
+	virtual ~RingBufferBase() {}
-			incrementRead(amount, n);
+
-			return HasReturnvaluesIF::RETURN_OK;
-		} else {
-			return HasReturnvaluesIF::RETURN_FAILED;
-		}
-	}
-	ReturnValue_t writeData(uint32_t amount) {
-		if (availableWriteSpace() >= amount || overwriteOld) {
-			incrementWrite(amount);
-			return HasReturnvaluesIF::RETURN_OK;
-		} else {
-			return HasReturnvaluesIF::RETURN_FAILED;
-		}
-	}
-	uint32_t availableReadData(uint8_t n = 0) const {
-		return ((write + size) - read[n]) % size;
-	}
-	uint32_t availableWriteSpace(uint8_t n = 0) const  {
-		//One less to avoid ambiguous full/empty problem.
-		return (((read[n] + size) - write - 1) % size);
-	}
 	bool isFull(uint8_t n = 0) {
 		return (availableWriteSpace(n) == 0);
 	}
 	bool isEmpty(uint8_t n = 0) {
-		return (availableReadData(n) == 0);
+		return (getAvailableReadData(n) == 0);
 	}
-	virtual ~RingBufferBase() {
 
+	size_t getAvailableReadData(uint8_t n = 0) const {
+		return ((write + size) - read[n]) % size;
 	}
-	uint32_t getRead(uint8_t n = 0) const {
+	size_t availableWriteSpace(uint8_t n = 0) const  {
-		return read[n];
+		//One less to avoid ambiguous full/empty problem.
+		return (((read[n] + size) - write - 1) % size);
 	}
-	void setRead(uint32_t read, uint8_t n = 0) {
+
-		if (read >= start && read < (start+size)) {
+	bool overwritesOld() const {
-			this->read[n] = read;
+		return overwriteOld;
 	}
+
+	size_t getMaxSize() const {
+		return size - 1;
 	}
-	uint32_t getWrite() const {
+
-		return write;
-	}
-	void setWrite(uint32_t write) {
-		this->write = write;
-	}
 	void clear() {
 		write = start;
 		for (uint8_t count = 0; count < N_READ_PTRS; count++) {
 			read[count] = start;
 		}
 	}
-	uint32_t writeTillWrap() {
+
+	size_t writeTillWrap() {
 		return (start + size) - write;
 	}
-	uint32_t readTillWrap(uint8_t n = 0) {
+
+	size_t readTillWrap(uint8_t n = 0) {
 		return (start + size) - read[n];
 	}
-	uint32_t getStart() const {
+
+	size_t getStart() const {
 		return start;
 	}
-	bool overwritesOld() const {
+
-		return overwriteOld;
-	}
-	uint32_t maxSize() const {
-		return size - 1;
-	}
 protected:
-	const uint32_t start;
+	const size_t start;
-	uint32_t write;
+	size_t write;
-	uint32_t read[N_READ_PTRS];
+	size_t read[N_READ_PTRS];
-	const uint32_t size;
+	const size_t size;
 	const bool overwriteOld;
+
 	void incrementWrite(uint32_t amount) {
 		write = ((write + amount - start) % size) + start;
 	}
 	void incrementRead(uint32_t amount, uint8_t n = 0) {
 		read[n] = ((read[n] + amount - start) % size) + start;
 	}
+
+	ReturnValue_t readData(uint32_t amount, uint8_t n = 0) {
+		if (getAvailableReadData(n) >= amount) {
+			incrementRead(amount, n);
+			return HasReturnvaluesIF::RETURN_OK;
+		} else {
+			return HasReturnvaluesIF::RETURN_FAILED;
+		}
+	}
+
+	ReturnValue_t writeData(uint32_t amount) {
+		if (availableWriteSpace() >= amount or overwriteOld) {
+			incrementWrite(amount);
+			return HasReturnvaluesIF::RETURN_OK;
+		} else {
+			return HasReturnvaluesIF::RETURN_FAILED;
+		}
+	}
+
+	size_t getRead(uint8_t n = 0) const {
+		return read[n];
+	}
+
+	void setRead(uint32_t read, uint8_t n = 0) {
+		if (read >= start && read < (start+size)) {
+			this->read[n] = read;
+		}
+	}
+
+	uint32_t getWrite() const {
+		return write;
+	}
+
+	void setWrite(uint32_t write) {
+		this->write = write;
+	}
 };
 
-#endif /* FRAMEWORK_CONTAINER_RINGBUFFERBASE_H_ */
+#endif /* FSFW_CONTAINER_RINGBUFFERBASE_H_ */

container/SimpleRingBuffer.cpp

@@ -1,27 +1,69 @@
 #include "SimpleRingBuffer.h"
-#include <string.h>
+#include <cstring>
 
-SimpleRingBuffer::SimpleRingBuffer(const size_t size, bool overwriteOld) :
+SimpleRingBuffer::SimpleRingBuffer(const size_t size, bool overwriteOld,
-		RingBufferBase<>(0, size, overwriteOld) {
+		size_t maxExcessBytes) :
-	buffer = new uint8_t[size];
+		RingBufferBase<>(0, size, overwriteOld),
+		maxExcessBytes(maxExcessBytes) {
+	if(maxExcessBytes > size) {
+		this->maxExcessBytes = size;
+	}
+	else {
+		this->maxExcessBytes = maxExcessBytes;
+	}
+	buffer = new uint8_t[size + maxExcessBytes];
 }
 
 SimpleRingBuffer::SimpleRingBuffer(uint8_t *buffer, const size_t size,
-        bool overwriteOld):
+		bool overwriteOld, size_t maxExcessBytes):
-        RingBufferBase<>(0, size, overwriteOld), buffer(buffer) {}
+        RingBufferBase<>(0, size, overwriteOld), buffer(buffer) {
-
+	if(maxExcessBytes > size) {
+		this->maxExcessBytes = size;
+	}
+	else {
+		this->maxExcessBytes = maxExcessBytes;
+	}
+}
 
 SimpleRingBuffer::~SimpleRingBuffer() {
 	delete[] buffer;
 }
 
-ReturnValue_t SimpleRingBuffer::writeData(const uint8_t* data,
+ReturnValue_t SimpleRingBuffer::getFreeElement(uint8_t **writePointer,
-		uint32_t amount) {
+        size_t amount) {
     if (availableWriteSpace() >= amount or overwriteOld) {
-		uint32_t amountTillWrap = writeTillWrap();
+        size_t amountTillWrap = writeTillWrap();
+        if (amountTillWrap < amount) {
+            if((amount - amountTillWrap + excessBytes) > maxExcessBytes) {
+                return HasReturnvaluesIF::RETURN_FAILED;
+            }
+            excessBytes = amount - amountTillWrap;
+        }
+        *writePointer = &buffer[write];
+        return HasReturnvaluesIF::RETURN_OK;
+    }
+    else {
+        return HasReturnvaluesIF::RETURN_FAILED;
+    }
+}
+
+void SimpleRingBuffer::confirmBytesWritten(size_t amount) {
+	if(getExcessBytes() > 0) {
+		moveExcessBytesToStart();
+	}
+	incrementWrite(amount);
+
+}
+
+ReturnValue_t SimpleRingBuffer::writeData(const uint8_t* data,
+		size_t amount) {
+	if (availableWriteSpace() >= amount or overwriteOld) {
+		size_t amountTillWrap = writeTillWrap();
 		if (amountTillWrap >= amount) {
+			// remaining size in buffer is sufficient to fit full amount.
 			memcpy(&buffer[write], data, amount);
-		} else {
+		}
+		else {
 			memcpy(&buffer[write], data, amountTillWrap);
 			memcpy(buffer, data + amountTillWrap, amount - amountTillWrap);
 		}
@@ -32,12 +74,13 @@ ReturnValue_t SimpleRingBuffer::writeData(const uint8_t* data,
 	}
 }
 
-ReturnValue_t SimpleRingBuffer::readData(uint8_t* data, uint32_t amount,
+ReturnValue_t SimpleRingBuffer::readData(uint8_t* data, size_t amount,
-		bool readRemaining, uint32_t* trueAmount) {
+		bool incrementReadPtr, bool readRemaining, size_t* trueAmount) {
-	uint32_t availableData = availableReadData(READ_PTR);
+	size_t availableData = getAvailableReadData(READ_PTR);
-	uint32_t amountTillWrap = readTillWrap(READ_PTR);
+	size_t amountTillWrap = readTillWrap(READ_PTR);
 	if (availableData < amount) {
 		if (readRemaining) {
+			// more data available than amount specified.
 			amount = availableData;
 		} else {
 			return HasReturnvaluesIF::RETURN_FAILED;
@@ -52,12 +95,27 @@ ReturnValue_t SimpleRingBuffer::readData(uint8_t* data, uint32_t amount,
 		memcpy(data, &buffer[read[READ_PTR]], amountTillWrap);
 		memcpy(data + amountTillWrap, buffer, amount - amountTillWrap);
 	}
+
+	if(incrementReadPtr) {
+		deleteData(amount, readRemaining);
+	}
 	return HasReturnvaluesIF::RETURN_OK;
 }
 
-ReturnValue_t SimpleRingBuffer::deleteData(uint32_t amount,
+size_t SimpleRingBuffer::getExcessBytes() const {
-		bool deleteRemaining, uint32_t* trueAmount) {
+    return excessBytes;
-	uint32_t availableData = availableReadData(READ_PTR);
+}
+
+void SimpleRingBuffer::moveExcessBytesToStart() {
+    if(excessBytes > 0) {
+        std::memcpy(buffer, &buffer[size], excessBytes);
+        excessBytes = 0;
+    }
+}
+
+ReturnValue_t SimpleRingBuffer::deleteData(size_t amount,
+		bool deleteRemaining, size_t* trueAmount) {
+	size_t availableData = getAvailableReadData(READ_PTR);
 	if (availableData < amount) {
 		if (deleteRemaining) {
 			amount = availableData;
@@ -71,4 +129,3 @@ ReturnValue_t SimpleRingBuffer::deleteData(uint32_t amount,
 	incrementRead(amount, READ_PTR);
 	return HasReturnvaluesIF::RETURN_OK;
 }
-

container/SimpleRingBuffer.h

@@ -1,8 +1,8 @@
-#ifndef FRAMEWORK_CONTAINER_SIMPLERINGBUFFER_H_
+#ifndef FSFW_CONTAINER_SIMPLERINGBUFFER_H_
-#define FRAMEWORK_CONTAINER_SIMPLERINGBUFFER_H_
+#define FSFW_CONTAINER_SIMPLERINGBUFFER_H_
 
 #include "RingBufferBase.h"
-#include <stddef.h>
+#include <cstddef>
 
 /**
  * @brief 	Circular buffer implementation, useful for buffering
@@ -16,53 +16,114 @@ class SimpleRingBuffer: public RingBufferBase<> {
 public:
     /**
      * This constructor allocates a new internal buffer with the supplied size.
+     *
      * @param size
-     * @param overwriteOld
+     * @param overwriteOld If the ring buffer is overflowing at a write
+     * operation, the oldest data will be overwritten.
+     * @param maxExcessBytes These additional bytes will be allocated in addtion
+     * to the specified size to accomodate contiguous write operations
+     * with getFreeElement.
+     *
      */
-	SimpleRingBuffer(const size_t size, bool overwriteOld);
+	SimpleRingBuffer(const size_t size, bool overwriteOld,
+	        size_t maxExcessBytes = 0);
 	/**
 	 * This constructor takes an external buffer with the specified size.
 	 * @param buffer
 	 * @param size
 	 * @param overwriteOld
+	 * If the ring buffer is overflowing at a write operartion, the oldest data
+     * will be overwritten.
+	 * @param maxExcessBytes
+	 * If the buffer can accomodate additional bytes for contigous write
+	 * operations with getFreeElement, this is the maximum allowed additional
+	 * size
 	 */
-	SimpleRingBuffer(uint8_t* buffer, const size_t size, bool overwriteOld);
+	SimpleRingBuffer(uint8_t* buffer, const size_t size, bool overwriteOld,
+	        size_t maxExcessBytes = 0);
 
 	virtual ~SimpleRingBuffer();
 
 	/**
-	 * Write to circular buffer and increment write pointer by amount
+	 * Write to circular buffer and increment write pointer by amount.
 	 * @param data
 	 * @param amount
+	 * @return -@c RETURN_OK if write operation was successfull
+	 * -@c RETURN_FAILED if
+	 */
+	ReturnValue_t writeData(const uint8_t* data, size_t amount);
+
+	/**
+	 * Returns a pointer to a free element. If the remaining buffer is
+	 * not large enough, the data will be written past the actual size
+	 * and the amount of excess bytes will be cached. This function
+	 * does not increment the write pointer!
+	 * @param writePointer Pointer to a pointer which can be used to write
+	 * contiguous blocks into the ring buffer
+	 * @param amount
 	 * @return
 	 */
-	ReturnValue_t writeData(const uint8_t* data, uint32_t amount);
+	ReturnValue_t getFreeElement(uint8_t** writePointer, size_t amount);
 
 	/**
-	 * Read from circular buffer at read pointer
+	 * This increments the write pointer and also copies the excess bytes
+	 * to the beginning. It should be called if the write operation
+	 * conducted after calling getFreeElement() was performed.
+	 * @return
+	 */
+	void confirmBytesWritten(size_t amount);
+
+	virtual size_t getExcessBytes() const;
+	/**
+	 * Helper functions which moves any excess bytes to the start
+	 * of the ring buffer.
+	 * @return
+	 */
+	virtual void moveExcessBytesToStart();
+
+	/**
+	 * Read from circular buffer at read pointer.
 	 * @param data
 	 * @param amount
+	 * @param incrementReadPtr
+	 * If this is set to true, the read pointer will be incremented.
+	 * If readRemaining is set to true, the read pointer will be incremented
+	 * accordingly.
 	 * @param readRemaining
-	 * @param trueAmount
+	 * If this is set to true, the data will be read even if the amount
+	 * specified exceeds the read data available.
+	 * @param trueAmount [out]
+	 * If readRemaining was set to true, the true amount read will be assigned
+	 * to the passed value.
 	 * @return
+	 * - @c RETURN_OK if data was read successfully
+	 * - @c RETURN_FAILED if not enough data was available and readRemaining
+	 *      was set to false.
 	 */
-	ReturnValue_t readData(uint8_t* data, uint32_t amount,
+	ReturnValue_t readData(uint8_t* data, size_t amount,
-	        bool readRemaining = false, uint32_t* trueAmount = nullptr);
+			bool incrementReadPtr = false, bool readRemaining = false,
+			size_t* trueAmount = nullptr);
 
 	/**
-	 * Delete data starting by incrementing read pointer
+	 * Delete data by incrementing read pointer.
 	 * @param amount
 	 * @param deleteRemaining
-	 * @param trueAmount
+	 * If the amount specified is larger than the remaing size to read and this
+	 * is set to true, the remaining amount will be deleted as well
+	 * @param trueAmount [out]
+	 * If deleteRemaining was set to true, the amount deleted will be assigned
+	 * to the passed value.
 	 * @return
 	 */
-	ReturnValue_t deleteData(uint32_t amount, bool deleteRemaining = false,
+	ReturnValue_t deleteData(size_t amount, bool deleteRemaining = false,
-	        uint32_t* trueAmount = nullptr);
+	        size_t* trueAmount = nullptr);
+
 private:
-//	static const uint8_t TEMP_READ_PTR = 1;
 	static const uint8_t READ_PTR = 0;
 	uint8_t* buffer = nullptr;
+	size_t maxExcessBytes;
+	size_t excessBytes = 0;
 };
 
-#endif /* FRAMEWORK_CONTAINER_SIMPLERINGBUFFER_H_ */
+#endif /* FSFW_CONTAINER_SIMPLERINGBUFFER_H_ */