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@45:40745c2036cf, 2013-12-19 (annotated)

Committer:
jengbrecht
Date:
Thu Dec 19 21:38:01 2013 +0000
Revision:
45:40745c2036cf
Parent:
17:2d7c4ea7491b
Child:
46:b30547bf07d5
Added a ton of documentation, made the notify start and stop methods private in MTSSerialFlowControl, added format method to the serial classes, fixed an issue in the bulk write method of MTSCircularBuffer

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