Mehrad Arashrad / libmDot

Library for LoRa communication using MultiTech MDOT.

Dependents:   mDot_LoRa_Connect_CSA_Light mDot_LoRa_Connect_CSA_RH_Temp

Fork of libmDot by MultiTech

MTSCircularBuffer.h@1:9f30fbe9e9c1, 2015-06-24 (annotated)

Committer:
Mike Fiore
Date:
Wed Jun 24 17:03:08 2015 -0500
Revision:
1:9f30fbe9e9c1
add README, LICENSE, headers, and library - from git tag mbed_24June2015

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Mike Fiore 1:9f30fbe9e9c1 1 /************************************************
Mike Fiore 1:9f30fbe9e9c1 2 * MultiTech MTDOT Library
Mike Fiore 1:9f30fbe9e9c1 3 * Copyright (c) 2015 MultiTech Systems
Mike Fiore 1:9f30fbe9e9c1 4 *
Mike Fiore 1:9f30fbe9e9c1 5 * See LICENSE file for license information
Mike Fiore 1:9f30fbe9e9c1 6 ***********************************************/
Mike Fiore 1:9f30fbe9e9c1 7
Mike Fiore 1:9f30fbe9e9c1 8 #ifndef MTSCIRCULARBUFFER_H
Mike Fiore 1:9f30fbe9e9c1 9 #define MTSCIRCULARBUFFER_H
Mike Fiore 1:9f30fbe9e9c1 10
Mike Fiore 1:9f30fbe9e9c1 11 #include "Utils.h"
Mike Fiore 1:9f30fbe9e9c1 12
Mike Fiore 1:9f30fbe9e9c1 13 namespace mts
Mike Fiore 1:9f30fbe9e9c1 14 {
Mike Fiore 1:9f30fbe9e9c1 15
Mike Fiore 1:9f30fbe9e9c1 16 /** This class provides a circular byte buffer meant for temporary storage
Mike Fiore 1:9f30fbe9e9c1 17 * during IO transactions. It contains many of the common methods you
Mike Fiore 1:9f30fbe9e9c1 18 * would expect from a circular buffer like read, write, and various
Mike Fiore 1:9f30fbe9e9c1 19 * methods for checking the size or status. It should be noted that
Mike Fiore 1:9f30fbe9e9c1 20 * this class does not include any special code for thread safety like
Mike Fiore 1:9f30fbe9e9c1 21 * a lock. In most cases this is not problematic, but is something
Mike Fiore 1:9f30fbe9e9c1 22 * to be aware of.
Mike Fiore 1:9f30fbe9e9c1 23 */
Mike Fiore 1:9f30fbe9e9c1 24 class MTSCircularBuffer
Mike Fiore 1:9f30fbe9e9c1 25 {
Mike Fiore 1:9f30fbe9e9c1 26 public:
Mike Fiore 1:9f30fbe9e9c1 27 /** Creates an MTSCircularBuffer object with the specified static size.
Mike Fiore 1:9f30fbe9e9c1 28 *
Mike Fiore 1:9f30fbe9e9c1 29 * @prarm bufferSize size of the buffer in bytes.
Mike Fiore 1:9f30fbe9e9c1 30 */
Mike Fiore 1:9f30fbe9e9c1 31 MTSCircularBuffer(int bufferSize);
Mike Fiore 1:9f30fbe9e9c1 32
Mike Fiore 1:9f30fbe9e9c1 33 /** Destructs an MTSCircularBuffer object and frees all related resources.
Mike Fiore 1:9f30fbe9e9c1 34 */
Mike Fiore 1:9f30fbe9e9c1 35 ~MTSCircularBuffer();
Mike Fiore 1:9f30fbe9e9c1 36
Mike Fiore 1:9f30fbe9e9c1 37 /** This method enables bulk reads from the buffer. If more data is
Mike Fiore 1:9f30fbe9e9c1 38 * requested then available it simply returns all remaining data within the
Mike Fiore 1:9f30fbe9e9c1 39 * buffer.
Mike Fiore 1:9f30fbe9e9c1 40 *
Mike Fiore 1:9f30fbe9e9c1 41 * @param data the buffer where data read will be added to.
Mike Fiore 1:9f30fbe9e9c1 42 * @param length the amount of data in bytes to be read into the buffer.
Mike Fiore 1:9f30fbe9e9c1 43 * @returns the total number of bytes that were read.
Mike Fiore 1:9f30fbe9e9c1 44 */
Mike Fiore 1:9f30fbe9e9c1 45 int read(char* data, int length);
Mike Fiore 1:9f30fbe9e9c1 46
Mike Fiore 1:9f30fbe9e9c1 47 /** This method reads a single byte from the buffer.
Mike Fiore 1:9f30fbe9e9c1 48 *
Mike Fiore 1:9f30fbe9e9c1 49 * @param data char where the read byte will be stored.
Mike Fiore 1:9f30fbe9e9c1 50 * @returns 1 if byte is read or 0 if no bytes available.
Mike Fiore 1:9f30fbe9e9c1 51 */
Mike Fiore 1:9f30fbe9e9c1 52 int read(char& data);
Mike Fiore 1:9f30fbe9e9c1 53
Mike Fiore 1:9f30fbe9e9c1 54 /** This method enables bulk writes to the buffer. If more data
Mike Fiore 1:9f30fbe9e9c1 55 * is requested to be written then space available the method writes
Mike Fiore 1:9f30fbe9e9c1 56 * as much data as possible and returns the actual amount written.
Mike Fiore 1:9f30fbe9e9c1 57 *
Mike Fiore 1:9f30fbe9e9c1 58 * @param data the byte array to be written.
Mike Fiore 1:9f30fbe9e9c1 59 * @param length the length of data to be written from the data paramter.
Mike Fiore 1:9f30fbe9e9c1 60 * @returns the number of bytes written to the buffer, which is 0 if
Mike Fiore 1:9f30fbe9e9c1 61 * the buffer is full.
Mike Fiore 1:9f30fbe9e9c1 62 */
Mike Fiore 1:9f30fbe9e9c1 63 int write(const char* data, int length);
Mike Fiore 1:9f30fbe9e9c1 64
Mike Fiore 1:9f30fbe9e9c1 65 /** This method writes a signle byte as a char to the buffer.
Mike Fiore 1:9f30fbe9e9c1 66 *
Mike Fiore 1:9f30fbe9e9c1 67 * @param data the byte to be written as a char.
Mike Fiore 1:9f30fbe9e9c1 68 * @returns 1 if the byte was written or 0 if the buffer was full.
Mike Fiore 1:9f30fbe9e9c1 69 */
Mike Fiore 1:9f30fbe9e9c1 70 int write(char data);
Mike Fiore 1:9f30fbe9e9c1 71
Mike Fiore 1:9f30fbe9e9c1 72 /** This method is used to setup a callback funtion when the buffer reaches
Mike Fiore 1:9f30fbe9e9c1 73 * a certain threshold. The threshold condition is checked after every read
Mike Fiore 1:9f30fbe9e9c1 74 * and write call is completed. The condition is made up of both a threshold
Mike Fiore 1:9f30fbe9e9c1 75 * value and operator. An example that would trigger a callback is if the
Mike Fiore 1:9f30fbe9e9c1 76 * threshold was 10, the operator GREATER, and there were 12 bytes added to an
Mike Fiore 1:9f30fbe9e9c1 77 * empty buffer.
Mike Fiore 1:9f30fbe9e9c1 78 *
Mike Fiore 1:9f30fbe9e9c1 79 * @param tptr a pointer to the object to be called when the condition is met.
Mike Fiore 1:9f30fbe9e9c1 80 * @param mptr a pointer to the function within the object to be called when
Mike Fiore 1:9f30fbe9e9c1 81 * the condition is met.
Mike Fiore 1:9f30fbe9e9c1 82 * @param threshold the value in bytes to be used as part of the condition.
Mike Fiore 1:9f30fbe9e9c1 83 * @param op the operator to be used in conjunction with the threshold
Mike Fiore 1:9f30fbe9e9c1 84 * as part of the condition.
Mike Fiore 1:9f30fbe9e9c1 85 */
Mike Fiore 1:9f30fbe9e9c1 86 template<typename T>
Mike Fiore 1:9f30fbe9e9c1 87 void attach(T *tptr, void( T::*mptr)(void), int threshold, RelationalOperator op) {
Mike Fiore 1:9f30fbe9e9c1 88 _threshold = threshold;
Mike Fiore 1:9f30fbe9e9c1 89 _op = op;
Mike Fiore 1:9f30fbe9e9c1 90 notify.attach(tptr, mptr);
Mike Fiore 1:9f30fbe9e9c1 91 }
Mike Fiore 1:9f30fbe9e9c1 92
Mike Fiore 1:9f30fbe9e9c1 93 /** This method is used to setup a callback funtion when the buffer reaches
Mike Fiore 1:9f30fbe9e9c1 94 * a certain threshold. The threshold condition is checked after every read
Mike Fiore 1:9f30fbe9e9c1 95 * and write call is completed. The condition is made up of both a threshold
Mike Fiore 1:9f30fbe9e9c1 96 * value and operator. An example that would trigger a callback is if the
Mike Fiore 1:9f30fbe9e9c1 97 * threshold was 10, the operator GREATER, and there were 12 bytes added to an
Mike Fiore 1:9f30fbe9e9c1 98 * empty buffer.
Mike Fiore 1:9f30fbe9e9c1 99 *
Mike Fiore 1:9f30fbe9e9c1 100 * @param fptr a pointer to the static function to be called when the condition
Mike Fiore 1:9f30fbe9e9c1 101 * is met.
Mike Fiore 1:9f30fbe9e9c1 102 * @param threshold the value in bytes to be used as part of the condition.
Mike Fiore 1:9f30fbe9e9c1 103 * @param op the operator to be used in conjunction with the threshold
Mike Fiore 1:9f30fbe9e9c1 104 * as part of the condition.
Mike Fiore 1:9f30fbe9e9c1 105 */
Mike Fiore 1:9f30fbe9e9c1 106 void attach(void(*fptr)(void), int threshold, RelationalOperator op) {
Mike Fiore 1:9f30fbe9e9c1 107 _threshold = threshold;
Mike Fiore 1:9f30fbe9e9c1 108 _op = op;
Mike Fiore 1:9f30fbe9e9c1 109 notify.attach(fptr);
Mike Fiore 1:9f30fbe9e9c1 110 }
Mike Fiore 1:9f30fbe9e9c1 111
Mike Fiore 1:9f30fbe9e9c1 112 /** This method returns the size of the storage space currently allocated for
Mike Fiore 1:9f30fbe9e9c1 113 * the buffer. This value is equivalent to the one passed into the constructor.
Mike Fiore 1:9f30fbe9e9c1 114 * This value is equal or greater than the size() of the buffer.
Mike Fiore 1:9f30fbe9e9c1 115 *
Mike Fiore 1:9f30fbe9e9c1 116 * @returns the allocated size of the buffer in bytes.
Mike Fiore 1:9f30fbe9e9c1 117 */
Mike Fiore 1:9f30fbe9e9c1 118 int capacity();
Mike Fiore 1:9f30fbe9e9c1 119
Mike Fiore 1:9f30fbe9e9c1 120 /** This method returns the amount of space left for writing.
Mike Fiore 1:9f30fbe9e9c1 121 *
Mike Fiore 1:9f30fbe9e9c1 122 * @returns numbers of unused bytes in buffer.
Mike Fiore 1:9f30fbe9e9c1 123 */
Mike Fiore 1:9f30fbe9e9c1 124 int remaining();
Mike Fiore 1:9f30fbe9e9c1 125
Mike Fiore 1:9f30fbe9e9c1 126 /** This method returns the number of bytes available for reading.
Mike Fiore 1:9f30fbe9e9c1 127 *
Mike Fiore 1:9f30fbe9e9c1 128 * @returns number of bytes currently in buffer.
Mike Fiore 1:9f30fbe9e9c1 129 */
Mike Fiore 1:9f30fbe9e9c1 130 int size();
Mike Fiore 1:9f30fbe9e9c1 131
Mike Fiore 1:9f30fbe9e9c1 132 /** This method returns whether the buffer is full.
Mike Fiore 1:9f30fbe9e9c1 133 *
Mike Fiore 1:9f30fbe9e9c1 134 * @returns true if full, otherwise false.
Mike Fiore 1:9f30fbe9e9c1 135 */
Mike Fiore 1:9f30fbe9e9c1 136 bool isFull();
Mike Fiore 1:9f30fbe9e9c1 137
Mike Fiore 1:9f30fbe9e9c1 138 /** This method returns whether the buffer is empty.
Mike Fiore 1:9f30fbe9e9c1 139 *
Mike Fiore 1:9f30fbe9e9c1 140 * @returns true if empty, otherwise false.
Mike Fiore 1:9f30fbe9e9c1 141 */
Mike Fiore 1:9f30fbe9e9c1 142 bool isEmpty();
Mike Fiore 1:9f30fbe9e9c1 143
Mike Fiore 1:9f30fbe9e9c1 144 /** This method clears the buffer. This is done through
Mike Fiore 1:9f30fbe9e9c1 145 * setting the internal read and write indexes to the same
Mike Fiore 1:9f30fbe9e9c1 146 * value and is therefore not an expensive operation.
Mike Fiore 1:9f30fbe9e9c1 147 */
Mike Fiore 1:9f30fbe9e9c1 148 void clear();
Mike Fiore 1:9f30fbe9e9c1 149
Mike Fiore 1:9f30fbe9e9c1 150
Mike Fiore 1:9f30fbe9e9c1 151 private:
Mike Fiore 1:9f30fbe9e9c1 152 int bufferSize; // total size of the buffer
Mike Fiore 1:9f30fbe9e9c1 153 char* buffer; // internal byte buffer as a character buffer
Mike Fiore 1:9f30fbe9e9c1 154 int readIndex; // read index for circular buffer
Mike Fiore 1:9f30fbe9e9c1 155 int writeIndex; // write index for circular buffer
Mike Fiore 1:9f30fbe9e9c1 156 int bytes; // available data
Mike Fiore 1:9f30fbe9e9c1 157 FunctionPointer notify; // function pointer used for the internal callback notification
Mike Fiore 1:9f30fbe9e9c1 158 int _threshold; // threshold for the notification
Mike Fiore 1:9f30fbe9e9c1 159 RelationalOperator _op; // operator that determines the direction of the threshold
Mike Fiore 1:9f30fbe9e9c1 160 void checkThreshold(); // private function that checks thresholds and processes notifications
Mike Fiore 1:9f30fbe9e9c1 161 };
Mike Fiore 1:9f30fbe9e9c1 162
Mike Fiore 1:9f30fbe9e9c1 163 }
Mike Fiore 1:9f30fbe9e9c1 164
Mike Fiore 1:9f30fbe9e9c1 165 #endif /* MTSCIRCULARBUFFER_H */