Lab-2.01: Ring Buffer Implementation¶

/**
 * @brief Ring buffer copy callback function to copy
 *  the element from the user into the ringbuffer.
 *
 * @param 1 destination
 * @param 2 source
 * @return 0 if successful, !=0 otherwise
 */
typedef int (*ringbuffer_ccb)(void *, const void *);

/**
 * @brief ringbuffer The ring buffer handler structure
 *
 */
typedef struct
{
  void *dataBuffer;          ///< buffer array reference
  uint32_t length;           ///< array length of buffer
  uint32_t headPos;          ///< current head position (first element)
  uint32_t tailPos;          ///< current tail position, (where a new element can inserted)
  uint32_t elmSize;          ///< Size of an element in the buffer (use sizeof operator of an element)
  ringbuffer_ccb cbbHandler; ///< Interface for callback function to copy data from and to the buffer
} ringbufferType;

/**
 * @brief Used to encode different errors.
 * This StatusTypes are used to send back meaningful
 * information to the caller of module functions.
 *
 */
typedef enum {
  RINGBUFFER_OK = 0,         ///< No error
  RINGBUFFER_OVERFLOW,       ///< Buffer is full and no new data can be inserted
  RINGBUFFER_EMPTY,          ///< current ring buffer is empty
  RINGBUFFER_ARGUMENT_ERROR, ///< Argument is not valid
  RINGBUFFER_ERROR           ///< Error in function or user copy callback function
} ringbuffer_StatusType;

/**
 * @brief Initialize a ring buffer structure
 *
 * @param rbHandler Reference to a ring buffer structure
 * @param buffer Reference to the buffer array
 * @param length The length of the buffer
 * @param elmSize Size of an element in the buffer
 * @param ccbHandler A function pointer to a element copy function
 * @return Status code -- see ringbuffer_StatusType
 */
ringbuffer_StatusType ringbuffer_init(
    ringbufferType *rbHandler,
    void *buffer,
    uint32_t length,
    uint32_t elmSize,
    ringbuffer_ccb ccbHandler);

/**
 * @brief Destroy ring buffer structure
 *
 * @param rbHandler Reference to an initialized ring buffer structure.
 * @return Address of the buffer.
 * @note: Use the returned address to free the memory
 *        if it has been allocated on heap.
 */
void *ringbuffer_destroy(ringbufferType *rbHandler);

/**
 * @brief Enqueue an element at the tail of the ring buffer.
 *
 * @param rbHandler Reference to the ring buffer structure
 * @param data The data to insert into the ring buffer
 * @return Status code -- see ringbuffer_StatusType
 */
ringbuffer_StatusType ringbuffer_enqueue(ringbufferType *rbHandler, void *data);

/**
 * @brief Dequeue an element from the head of the ring buffer
 *
 * @param rbHandler Reference to the ringbuffer structure
 * @param data The data which will be dequeued from the ringbuffer
 * @return Status code -- see ringbuffer_StatusType
 */
ringbuffer_StatusType ringbuffer_dequeue(ringbufferType *rbHandler, void **data);

/**
 * @brief Return the reference to the data
 *        at the head of the ring buffer without dequeuing it.
 *
 * @param rbHandler Reference to the ring buffer structure
 * @return Data stored in the element at the head of the ring buffer,
 *         or NULL if the queue is empty.
 */
void *ringbuffer_peek(const ringbufferType *rbHandler);

/**
 * @brief Number of elements stored in the ring buffer
 *
 * @param rbHandler Reference to the ring buffer structure
 * @return uint32_t Number of elements in the ring buffer
 */
uint32_t ringbuffer_size(const ringbufferType *rbHandler);

/**
 * @brief Check whether buffer is full
 *
 * @param rbHandler Reference to the ring buffer structure
 * @return True if buffer is full, False otherwise
 */
bool ringbuffer_isFull(const ringbufferType *rbHandler);

/**
 * @brief Check whether buffer is empty
 *
 * @param rbHandler Reference to the ring buffer structure
 * @return True if buffer is empty, False otherwise
 */
bool ringbuffer_isEmpty(const ringbufferType *rbHandler);

/**
 * @brief More specific interface to handle C-Strings with a ring buffer.
 *         Used to initialize the underlining generic ring buffer.
 *
 * @param strRingBuf Reference to a ring buffer structure.
 * @param buffer Reference to a char array to manage the C-strings
 * @param length The length of the char array
 * @param strLength The max length of a C-string stored within the buffer
 * @return ringbuffer_status_t RINGBUFFER_OK if successful
 */
ringbuffer_StatusType strRingbuffer_init(
    ringbufferType *strRingBuf,
    char **buffer,
    uint32_t length,
    uint32_t strLength);

/**
 * @brief Destroy string ring buffer structure
 *
 * @param strRingBuf Reference to the ring buffer structure.
 * @return Address of the buffer.
 * @note: Use the returned address to free the memory
 *        if it has been allocated on heap.
 */
char **strRingbuffer_destroy(ringbufferType *strRingBuf);

/**
 * @brief Enqueue a C-String.
 *        The C-String is truncated if it is longer than the max
 *        possible strLength.
 *
 * @param strRingBuf Reference to the ring buffer structure
 * @param data A reference to a valid C-String inserted into the ring buffer.
 * @return Status code -- see ringbuffer_StatusType
 */
ringbuffer_StatusType strRingbuffer_enqueue(
    ringbufferType *strRingBuf,
    const char *str);

/**
 * @brief Dequeue a C-String from the head of the ring buffer
 *
 * @param strRingBuf Reference to the ringbuffer structure
 * @return Reference to the dequeued string or NULL for an empty buffer
 */
char *strRingbuffer_dequeue(ringbufferType *strRingBuf);

/**
 * @brief Return the reference to the C-String at the head
 *        of the ring buffer without dequeuing it.
 *
 * @param strRingBuf Reference to the ring buffer structure
 * @return Data stored in the element at the head of the ring buffer,
 *         or NULL if the ring buffer is empty.
 */
char *strRingbuffer_peek(const ringbufferType *strRingBuf);