Multi-Hackers / SocketModem

A library for talking to Multi-Tech's Cellular SocketModem Devices.

Dependents:   M2X_dev axeda_wrapper_dev MTS_M2x_Example1 MTS_Cellular_Connect_Example ... more

utils/MTSCircularBuffer.h@67:1003b410f781, 2013-12-23 (annotated)

Committer:
sgodinez
Date:
Mon Dec 23 19:55:31 2013 +0000
Revision:
67:1003b410f781
Parent:
64:0ca9c7123ffc
Child:
141:571e0ef6c8dc
Changed MTSCircularBuffer names for size, capacity, and remaining

Who changed what in which revision?

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