Made RingBuf methods thread safe

Author: wizard97

README.md

@@ -1,6 +1,6 @@
 # ArduinoRingBuffer
 
-This is a simple ring buffer library for the Arduino. It is written in vanilla C, and can easily be modified to work with other platforms simply be removing the `#include "Arduino.h" `.  It can buffer any fixed size object (ints, floats, structs, etc...).
+This is a simple ring buffer library for the Arduino. It is written in vanilla C, and can easily be modified to work with other platforms.  It can buffer any fixed size object (ints, floats, structs, etc...).
 
 ## Project History
 I needed a way to buffer sensor events for a group engineering IOT project that I was working on at Cornell. We needed to record changes in IR trip wires that happened in ms timeframes, and tight loop polling was not working. We needed interrupts and a buffering library. I couldn't find any suitable Arduino Libraries that could buffer any sized object, so I wrote my own.
@@ -62,7 +62,7 @@ Append an element to the buffer, where object is a pointer to object you wish to
 void *peek(RingBuf *self, unsigned int num);
 ```
 
-Peek at the num'th element in the buffer. Returns a void pointer to the location of the num'th element. If num is out of bounds or the num'th element is empty, a NULL pointer is returned. Cast the result of this call into a pointer of whatever type you are storing in the buffer. Note that this gives you direct memory access to the location of the num'th element in the buffer, allowing you to directly edit elements in the buffer.
+Peek at the num'th element in the buffer. Returns a void pointer to the location of the num'th element. If num is out of bounds or the num'th element is empty, a NULL pointer is returned. Cast the result of this call into a pointer of whatever type you are storing in the buffer. Note that this gives you direct memory access to the location of the num'th element in the buffer, allowing you to directly edit elements in the buffer. Note that while all of RingBuf's public methods are thread safe (including this one), directly using the pointer returned from this method is not thread safe. To use this returned pointer safely, disable interrupts first with `noInterrupts()`, do whatever you need to do with the pointer, then you can reenable interrupts by calling `interrupts()`.
 
 ### pull()
 
@@ -72,6 +72,7 @@ void *pull(RingBuf *self, void *object);
 
 Pull the first element out of the buffer. The first element is copied into the location pointed to by object. Returns a NULL pointer if the buffer is empty, otherwise returns object.
 
+
 ### numElements()
 ```
 unsigned int numElements(RingBuf *self);

RingBuf.c

@@ -6,6 +6,7 @@
 */
 #include "RingBuf.h"
 #include <string.h>
+#include <util/atomic.h>
 
 /////// Constructor //////////
 RingBuf *RingBuf_new(int size, int len)
@@ -83,56 +84,97 @@ int RingBufIncrStart(RingBuf *self)
 // Add an object struct to RingBuf
 int RingBufAdd(RingBuf *self, void *object)
 {
-  int index = self->next_end_index(self);
-  if (index < 0) return -1;
-  memcpy(self->buf + index*self->size, object, self->size);
-  //if not empty incriment end index
-  if (!self->isEmpty(self)) self->incr_end_index(self);
-  self->elements++;
-  return index;
+  int index;
+  // Perform all atomic opertaions
+  ATOMIC_BLOCK(ATOMIC_RESTORESTATE)
+  {
+    index = self->next_end_index(self);
+    //if not full
+    if (index >= 0)
+    {
+      if (!self->isEmpty(self)) self->incr_end_index(self);
+      self->elements++;
+      memcpy(self->buf + index*self->size, object, self->size);
+    }
+  }
 
+  return index;
 }
 
 // Return pointer to num element, return null on empty or num out of bounds
 void *RingBufPeek(RingBuf *self, unsigned int num)
 {
-  //empty or out of bounds
-  if (self->isEmpty(self) || num > self->elements - 1) return NULL;
-
-  return &self->buf[((self->start + num)%self->len)*self->size];
+  void *ret;
+  // Perform all atomic opertaions
+  ATOMIC_BLOCK(ATOMIC_RESTORESTATE)
+  {
+    //empty or out of bounds
+    if (self->isEmpty(self) || num > self->elements - 1) ret = NULL;
+    else ret = &self->buf[((self->start + num)%self->len)*self->size];
+  }
+  return ret;
 }
 
 // Returns and removes first buffer element
 void *RingBufPull(RingBuf *self, void *object)
 {
-  if (self->isEmpty(self)) return NULL;
-  // Copy Object
-  memcpy(object, self->buf+self->start*self->size, self->size);
-  //Don't mess things up to much, even if called on an empty buffer
-  if (!self->isEmpty(self))
+  void *ret;
+  // Perform all atomic opertaions
+  ATOMIC_BLOCK(ATOMIC_RESTORESTATE)
   {
-    self->elements--;
-    // don't incriment if removing last element
-    if (!self->isEmpty(self)) self->incr_start_index(self);
+    if (self->isEmpty(self)) ret = NULL;
+    // Else copy Object
+    else
+    {
+      memcpy(object, self->buf+self->start*self->size, self->size);
+      self->elements--;
+      // don't incriment start if removing last element
+      if (!self->isEmpty(self)) self->incr_start_index(self);
+      ret = object;
+    }
   }
 
-  return object;
+  return ret;
 }
 
 // Returns number of elemnts in buffer
 unsigned int RingBufNumElements(RingBuf *self)
 {
-  return self->elements;
+  unsigned int elements;
+
+  // Perform all atomic opertaions
+  ATOMIC_BLOCK(ATOMIC_RESTORESTATE)
+  {
+    elements = self->elements;
+  }
+
+  return elements;
 }
 
 // Returns true if buffer is full
 bool RingBufIsFull(RingBuf *self)
 {
-  return self->elements == self->len;
+  bool ret;
+
+  // Perform all atomic opertaions
+  ATOMIC_BLOCK(ATOMIC_RESTORESTATE)
+  {
+    ret = self->elements == self->len;
+  }
+
+  return ret;
 }
 
 // Returns true if buffer is empty
 bool RingBufIsEmpty(RingBuf *self)
 {
-  return !self->elements;
+  bool ret;
+
+  // Perform all atomic opertaions
+  ATOMIC_BLOCK(ATOMIC_RESTORESTATE)
+  {
+    ret = !self->elements;
+  }
+
+  return ret;
 }

examples/RingBufInterruptsExample/RingBufInterruptsExample.ino

@@ -49,7 +49,7 @@ void loop() {
   // Print the number of elements
   Serial.print("There are: ");
   Serial.print(buf->numElements(buf));
-  Serial.println(" elements in the ring buffer");
+  Serial.println(" element(s) in the ring buffer");
 
   // Check if empty
   if (buf->isEmpty(buf))
@@ -115,4 +115,3 @@ void print_buf_contents()
   Serial.println("______Done dumping contents_______");
 
 }
-

library.properties

@@ -6,4 +6,4 @@ sentence=A library for buffering items into a ring (circular) buffer
 paragraph=This library is perfect for capturing pin states, timestamps, etc.. during an ISR. Then in void loop(), the buffer can be asynchronously processed whenever your program has free time.
 category=Data Storage
 url=https://github.com/wizard97/ArduinoRingBuffer
-architectures=*
+architectures=avr