MultiTech / MTS-Utils

Utility library for MTS Socket Modem Arduino Shield devices from Multi-Tech Systems

Dependents:   mtsas mtsas thermostat_fan_demo--fan mtsas ... more

NOTE: MTS-Utils has moved to GitHub. This version will not be updated. For updates, go to the GitHub version.

MTSCircularBuffer.h@5:48d0ea2fe332, 2014-05-19 (annotated)

Committer:
Mike Fiore
Date:
Mon May 19 14:39:33 2014 -0500
Revision:
5:48d0ea2fe332
Parent:
3:08a693917d8c
Child:
6:fca9bc67b15f
add Utils.h, replace inclusion of Vars.h with Utils.h

Who changed what in which revision?

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