getFreeELement function added

container/SimpleRingBuffer.cpp

@@ -1,22 +1,71 @@
-#include "SimpleRingBuffer.h"
+#include "../container/SimpleRingBuffer.h"
-#include <string.h>
+#include <cstring>
 
-SimpleRingBuffer::SimpleRingBuffer(uint32_t size, bool overwriteOld) :
+SimpleRingBuffer::SimpleRingBuffer(const size_t size, bool overwriteOld,
-		RingBufferBase<>(0, size, overwriteOld), buffer(NULL) {
+		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, size_t maxExcessBytes):
+        RingBufferBase<>(0, size, overwriteOld), buffer(buffer) {
+	if(maxExcessBytes > size) {
+		this->maxExcessBytes = size;
+	}
+	else {
+		this->maxExcessBytes = maxExcessBytes;
+	}
+}
+
 
 SimpleRingBuffer::~SimpleRingBuffer() {
 	delete[] buffer;
 }
 
+
+ReturnValue_t SimpleRingBuffer::getFreeElement(uint8_t **writePointer,
+        size_t amount) {
+    if (availableWriteSpace() >= amount or overwriteOld) {
+        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,
-		uint32_t amount) {
+		size_t amount) {
-	if (availableWriteSpace() >= amount || overwriteOld) {
+	if (availableWriteSpace() >= amount or overwriteOld) {
-		uint32_t amountTillWrap = writeTillWrap();
+		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);
 		}
@@ -27,18 +76,19 @@ 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;
 		}
 	}
-	if (trueAmount != NULL) {
+	if (trueAmount != nullptr) {
 		*trueAmount = amount;
 	}
 	if (amountTillWrap >= amount) {
@@ -47,12 +97,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;
@@ -60,9 +125,11 @@ ReturnValue_t SimpleRingBuffer::deleteData(uint32_t amount,
 			return HasReturnvaluesIF::RETURN_FAILED;
 		}
 	}
-	if (trueAmount != NULL) {
+	if (trueAmount != nullptr) {
 		*trueAmount = amount;
 	}
 	incrementRead(amount, READ_PTR);
 	return HasReturnvaluesIF::RETURN_OK;
 }
+
+

container/SimpleRingBuffer.h

@@ -1,20 +1,127 @@
 #ifndef FRAMEWORK_CONTAINER_SIMPLERINGBUFFER_H_
 #define FRAMEWORK_CONTAINER_SIMPLERINGBUFFER_H_
 
-#include "RingBufferBase.h"
+#include "../container/RingBufferBase.h"
-#include <stddef.h>
+#include <cstddef>
 
+/**
+ * @brief 	Circular buffer implementation, useful for buffering
+ *          into data streams.
+ * @details
+ * Note that the deleteData() has to be called to increment the read pointer.
+ * This class allocated dynamically, so
+ * @ingroup containers
+ */
 class SimpleRingBuffer: public RingBufferBase<> {
 public:
-	SimpleRingBuffer(uint32_t size, bool overwriteOld);
+    /**
+     * This constructor allocates a new internal buffer with the supplied size.
+     *
+     * @param size
+     * @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,
+	        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,
+	        size_t maxExcessBytes = 0);
+
 	virtual ~SimpleRingBuffer();
-	ReturnValue_t writeData(const uint8_t* data, uint32_t amount);
+
-	ReturnValue_t readData(uint8_t* data, uint32_t amount, bool readRemaining = false, uint32_t* trueAmount = NULL);
+	/**
-	ReturnValue_t deleteData(uint32_t amount, bool deleteRemaining = false, uint32_t* trueAmount = NULL);
+	 * 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 getFreeElement(uint8_t** writePointer, size_t amount);
+
+	/**
+	 * 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
+	 * 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, size_t amount,
+			bool incrementReadPtr = false, bool readRemaining = false,
+			size_t* trueAmount = nullptr);
+
+	/**
+	 * Delete data by incrementing read pointer.
+	 * @param amount
+	 * @param deleteRemaining
+	 * 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(size_t amount, bool deleteRemaining = false,
+	        size_t* trueAmount = nullptr);
 private:
-//	static const uint8_t TEMP_READ_PTR = 1;
 	static const uint8_t READ_PTR = 0;
-	uint8_t* buffer;
+	uint8_t* buffer = nullptr;
+	size_t maxExcessBytes;
+	size_t excessBytes = 0;
 };
 
 #endif /* FRAMEWORK_CONTAINER_SIMPLERINGBUFFER_H_ */