Add raw iteration over queue elements; add buffered UART test double

Author: ryanplusplus

include/tiny_queue.h

@@ -15,6 +15,13 @@ typedef struct {
   tiny_ring_buffer_t ring_buffer;
 } tiny_queue_t;
 
+typedef struct
+{
+  unsigned offset;
+  const uint8_t* buffer;
+  unsigned buffer_capacity;
+} tiny_queue_raw_element_iterator_t;
+
 /*!
  * Initialize a queue with the provided buffer.
  */
@@ -63,4 +70,34 @@ void tiny_queue_peek_size(tiny_queue_t* self, uint16_t* size, uint16_t index);
  */
 uint16_t tiny_queue_count(tiny_queue_t* self);
 
+/*!
+ * Get an iterator over the raw bytes of an element. This allows for optimized access to
+ * an element that cannot be read out of the queue in its entirety.
+ */
+tiny_queue_raw_element_iterator_t tiny_queue_raw_element_iterator(
+  tiny_queue_t* instance,
+  uint16_t index);
+
+/*!
+ * View the next byte in the element without advancing the iterator.
+ */
+static inline uint8_t tiny_queue_raw_element_iterator_peek(
+  tiny_queue_raw_element_iterator_t* instance)
+{
+  return instance->buffer[instance->offset];
+}
+
+/*!
+ * @warning This does no bounds checking. The client must ensure that the iterator is not
+ *    advanced past the end of the buffer.
+ */
+static inline void tiny_queue_raw_element_iterator_advance(
+  tiny_queue_raw_element_iterator_t* instance)
+{
+  instance->offset++;
+  if(instance->offset >= instance->buffer_capacity) {
+    instance->offset = 0;
+  }
+}
+
 #endif

library.json

@@ -13,7 +13,7 @@
       "maintainer": true
     }
   ],
-  "version": "7.0.2",
+  "version": "7.1.0",
   "frameworks": "*",
   "platforms": "*",
   "export": {

src/tiny_queue.c

@@ -49,30 +49,30 @@ static void discard_element(tiny_queue_t* self, uint16_t element_size)
   }
 }
 
-static void peek_element_size_at_ring_buffer_index(tiny_queue_t* self, uint16_t* element_size, uint16_t location)
+static void peek_element_size_at_ring_buffer_index(tiny_queue_t* self, uint16_t* element_size, unsigned location)
 {
   uint8_t* destination = (uint8_t*)element_size;
-  for(uint16_t i = location; i < location + sizeof(uint16_t); i++) {
+  for(unsigned i = location; i < location + sizeof(uint16_t); i++) {
     tiny_ring_buffer_at(&self->ring_buffer, i, destination);
     destination++;
   }
 }
 
-static uint16_t ring_buffer_index_for_element_index(tiny_queue_t* self, uint16_t element_index)
+static unsigned ring_buffer_index_for_element_index(tiny_queue_t* self, uint16_t element_index)
 {
   uint16_t element_size;
-  uint16_t location = 0;
+  unsigned location = 0;
   for(uint16_t i = 0; i < element_index; i++) {
     peek_element_size_at_ring_buffer_index(self, &element_size, location);
     location += (uint16_t)(element_size + sizeof(uint16_t));
   }
   return location;
 }
 
-static void peek_element_at_ring_buffer_index(tiny_queue_t* self, void* element, uint16_t element_size, uint16_t location)
+static void peek_element_at_ring_buffer_index(tiny_queue_t* self, void* element, uint16_t element_size, unsigned location)
 {
   uint8_t* destination = element;
-  for(uint16_t i = location; i < location + element_size; i++) {
+  for(unsigned i = location; i < location + element_size; i++) {
     tiny_ring_buffer_at(&self->ring_buffer, i, destination);
     destination++;
   }
@@ -111,20 +111,20 @@ void tiny_queue_discard(tiny_queue_t* self)
 
 void tiny_queue_peek(tiny_queue_t* self, void* element, uint16_t* size_storage, uint16_t element_index)
 {
-  uint16_t i = ring_buffer_index_for_element_index(self, element_index);
+  unsigned i = ring_buffer_index_for_element_index(self, element_index);
   peek_element_size_at_ring_buffer_index(self, size_storage, i);
   peek_element_at_ring_buffer_index(self, element, *size_storage, i + sizeof(uint16_t));
 }
 
 void tiny_queue_peek_partial(tiny_queue_t* self, void* element, uint16_t size, uint16_t offset, uint16_t element_index)
 {
-  uint16_t i = ring_buffer_index_for_element_index(self, element_index);
+  unsigned i = ring_buffer_index_for_element_index(self, element_index);
   peek_element_at_ring_buffer_index(self, element, size, (uint16_t)(i + offset + sizeof(uint16_t)));
 }
 
 void tiny_queue_peek_size(tiny_queue_t* self, uint16_t* size_storage, uint16_t element_index)
 {
-  uint16_t i = ring_buffer_index_for_element_index(self, element_index);
+  unsigned i = ring_buffer_index_for_element_index(self, element_index);
   peek_element_size_at_ring_buffer_index(self, size_storage, i);
 }
 
@@ -141,3 +141,20 @@ void tiny_queue_init(
   self->element_count = 0;
   tiny_ring_buffer_init(&self->ring_buffer, storage, sizeof(uint8_t), storage_size);
 }
+
+tiny_queue_raw_element_iterator_t tiny_queue_raw_element_iterator(
+  tiny_queue_t* instance,
+  uint16_t index)
+{
+  unsigned ring_buffer_index = ring_buffer_index_for_element_index(instance, index);
+  unsigned offset = ring_buffer_index + (unsigned)sizeof(uint16_t) + instance->ring_buffer.tail;
+  if(offset >= tiny_ring_buffer_capacity(&instance->ring_buffer)) {
+    offset -= tiny_ring_buffer_capacity(&instance->ring_buffer);
+  }
+
+  return (tiny_queue_raw_element_iterator_t){
+    .offset = offset,
+    .buffer = instance->ring_buffer.buffer,
+    .buffer_capacity = tiny_ring_buffer_capacity(&instance->ring_buffer),
+  };
+}

test/include/double/tiny_buffered_uart_double.hpp

@@ -0,0 +1,51 @@
+/*!
+ * @file
+ * @brief UART test double.
+ */
+
+#ifndef tiny_buffered_uart_double_hpp
+#define tiny_buffered_uart_double_hpp
+
+extern "C" {
+#include "hal/i_tiny_buffered_uart.h"
+#include "tiny_event.h"
+}
+
+typedef struct {
+  i_tiny_buffered_uart_t interface;
+  tiny_event_t receive;
+  tiny_event_t send_complete;
+  bool automatic_send_complete;
+  bool sending;
+  bool send_completed;
+  bool receive_pending;
+  const void* receive_buffer;
+  uint16_t receive_buffer_size;
+} tiny_buffered_uart_double_t;
+
+/*!
+ * Initializes a buffered UART double.
+ */
+void tiny_buffered_uart_double_init(tiny_buffered_uart_double_t* self);
+
+/*!
+ * True if a byte was sent without send completing.
+ */
+bool tiny_buffered_uart_double_sending(tiny_buffered_uart_double_t* self);
+
+/*!
+ * Causes the double to raise a send complete event.
+ */
+void tiny_buffered_uart_double_trigger_send_complete(tiny_buffered_uart_double_t* self);
+
+/*!
+ * Causes the double to raise a receive event.
+ */
+void tiny_buffered_uart_double_trigger_receive(tiny_buffered_uart_double_t* self, const void* buffer, uint16_t buffer_size);
+
+/*!
+ * When enabled, the double will raise a send complete event when a buffer is sent. Defaults to disabled.
+ */
+void tiny_buffered_uart_double_configure_automatic_send_complete(tiny_buffered_uart_double_t* self, bool enabled);
+
+#endif

test/src/tiny_buffered_uart_double.cpp

@@ -0,0 +1,86 @@
+/*!
+ * @file
+ * @brief
+ */
+
+#include "CppUTestExt/MockSupport.h"
+#include "double/tiny_buffered_uart_double.hpp"
+
+static void send(i_tiny_buffered_uart_t* _self, const void* buffer, uint16_t buffer_size)
+{
+  auto self = reinterpret_cast<tiny_buffered_uart_double_t*>(_self);
+  self->sending = true;
+
+  if(self->automatic_send_complete) {
+    self->send_completed = true;
+  }
+
+  mock()
+    .actualCall("send")
+    .onObject(self)
+    .withMemoryBufferParameter("buffer", reinterpret_cast<const uint8_t*>(buffer), buffer_size);
+}
+
+static i_tiny_event_t* on_send_complete(i_tiny_buffered_uart_t* _self)
+{
+  auto self = reinterpret_cast<tiny_buffered_uart_double_t*>(_self);
+  return &self->send_complete.interface;
+}
+
+static i_tiny_event_t* on_receive(i_tiny_buffered_uart_t* _self)
+{
+  auto self = reinterpret_cast<tiny_buffered_uart_double_t*>(_self);
+  return &self->receive.interface;
+}
+
+static void run(i_tiny_buffered_uart_t* _self)
+{
+  auto self = reinterpret_cast<tiny_buffered_uart_double_t*>(_self);
+
+  if(self->send_completed) {
+    self->sending = false;
+    self->send_completed = false;
+    tiny_event_publish(&self->send_complete, nullptr);
+  }
+
+  if(self->receive_pending) {
+    self->receive_pending = false;
+    tiny_buffered_uart_on_receive_args_t args = { self->receive_buffer, self->receive_buffer_size };
+    tiny_event_publish(&self->receive, &args);
+  }
+}
+
+static const i_tiny_buffered_uart_api_t api = { send, on_send_complete, on_receive, run };
+
+void tiny_buffered_uart_double_init(tiny_buffered_uart_double_t* self)
+{
+  self->interface.api = &api;
+  self->sending = false;
+  self->automatic_send_complete = false;
+
+  tiny_event_init(&self->send_complete);
+  tiny_event_init(&self->receive);
+}
+
+bool tiny_buffered_uart_double_sending(tiny_buffered_uart_double_t* self)
+{
+  return self->sending;
+}
+
+void tiny_buffered_uart_double_trigger_send_complete(tiny_buffered_uart_double_t* self)
+{
+  self->sending = false;
+  self->send_completed = true;
+}
+
+void tiny_buffered_uart_double_trigger_receive(tiny_buffered_uart_double_t* self, const void* buffer, uint16_t buffer_size)
+{
+  self->receive_buffer = buffer;
+  self->receive_buffer_size = buffer_size;
+  self->receive_pending = true;
+}
+
+void tiny_buffered_uart_double_configure_automatic_send_complete(tiny_buffered_uart_double_t* self, bool enabled)
+{
+  self->automatic_send_complete = enabled;
+}

test/tests/tiny_queue_test.cpp

@@ -98,7 +98,7 @@ TEST_GROUP(tiny_queue)
     CHECK_EQUAL(element, dequeued_element_storage);
   }
 
-  bool given_that_large_element_has_been_enqueued(uint8_t * element)
+  bool given_that_large_element_has_been_enqueued(uint8_t* element)
   {
     return tiny_queue_enqueue(&self, (void*)element, large_element_size);
   }
@@ -115,7 +115,7 @@ TEST_GROUP(tiny_queue)
     CHECK_FALSE(given_that_large_element_has_been_enqueued(some_large_element_1));
   }
 
-  void dequeueing_should_yield(uint8_t * element)
+  void dequeueing_should_yield(uint8_t* element)
   {
     uint8_t dequeued_element_storage[large_element_size];
     memset(dequeued_element_storage, 0, sizeof(dequeued_element_storage));
@@ -134,7 +134,7 @@ TEST_GROUP(tiny_queue)
     tiny_queue_discard(&self);
   }
 
-  void peeking_should_yield(uint8_t * element, size_t element_size, uint16_t element_index)
+  void peeking_should_yield(uint8_t* element, size_t element_size, uint16_t element_index)
   {
     uint8_t peekedElementStorage[std::numeric_limits<uint8_t>::max()];
     memset(peekedElementStorage, 0, sizeof(peekedElementStorage));
@@ -148,7 +148,7 @@ TEST_GROUP(tiny_queue)
     }
   }
 
-  void peeking_from_the_front_of_the_queue_should_yield(uint8_t * element)
+  void peeking_from_the_front_of_the_queue_should_yield(uint8_t* element)
   {
     peeking_should_yield(element, large_element_size, 0);
   }
@@ -226,6 +226,41 @@ TEST_GROUP(tiny_queue)
   {
     CHECK_EQUAL(expected, tiny_queue_count(&self));
   }
+
+  void given_that_the_queue_has_been_initialized_with_storage_size(uint16_t size)
+  {
+    CHECK(size <= sizeof(buffer));
+
+    tiny_queue_init(
+      &self,
+      buffer,
+      size);
+  }
+
+  template <typename T>
+  void given_that_an_element_has_been_enqueued(T element)
+  {
+    CHECK(tiny_queue_enqueue(&self, &element, sizeof(element)));
+  }
+
+  void should_be_able_to_iterate_over_element_bytes(uint16_t index)
+  {
+    uint8_t expected[UINT8_MAX];
+    uint16_t size;
+    tiny_queue_peek(&self, expected, &size, index);
+
+    tiny_queue_raw_element_iterator_t iterator = tiny_queue_raw_element_iterator(&self, index);
+    for(uint16_t i = 0; i < size; i++) {
+      uint8_t byte = tiny_queue_raw_element_iterator_peek(&iterator);
+      tiny_queue_raw_element_iterator_advance(&iterator);
+      CHECK_EQUAL(expected[i], byte);
+    }
+  }
+
+  void given_that_an_element_has_been_discarded()
+  {
+    tiny_queue_discard(&self);
+  }
 };
 
 TEST(tiny_queue, should_be_able_to_enqueue_and_dequeue_a_small_element)
@@ -371,3 +406,23 @@ TEST(tiny_queue, should_know_how_many_elements_are_queued_after_some_have_been_d
   given_that_n_elements_have_been_discarded(2);
   the_element_count_should_be(2);
 }
+
+TEST(tiny_queue, should_allow_the_bytes_of_an_element_to_be_iterated_over)
+{
+  given_that_the_queue_has_been_initialized();
+  given_that_an_element_has_been_enqueued((uint32_t)0x12345678);
+  given_that_an_element_has_been_enqueued((uint16_t)0xABCD);
+  should_be_able_to_iterate_over_element_bytes(0);
+  should_be_able_to_iterate_over_element_bytes(1);
+}
+
+TEST(tiny_queue, should_allow_the_bytes_of_an_element_to_be_iterated_over_even_if_the_element_wraps)
+{
+  given_that_the_queue_has_been_initialized_with_storage_size(12);
+  given_that_an_element_has_been_enqueued((uint16_t)0xABCD);
+  given_that_an_element_has_been_enqueued((uint32_t)0x12345678);
+  given_that_an_element_has_been_discarded();
+  given_that_an_element_has_been_enqueued((uint32_t)0x87654321);
+
+  should_be_able_to_iterate_over_element_bytes(1);
+}