canuck lehead / libmDot_1012-hotifx

libmDot 1.0.12-hotfix

MTS-Utils/MTSCircularBuffer.h@0:5f84bdd949b8, 2016-07-17 (annotated)

Committer:
shaunkrnelson
Date:
Sun Jul 17 00:03:03 2016 +0000
Revision:
0:5f84bdd949b8
1.0.12-hotfix

Who changed what in which revision?

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