nguyen hoang / libmDot-dev-mbed5

khang_91

MTS-Lora/vendor/multitech/MTS-Utils/MTSCircularBuffer.h@183:16414698889c, 2020-06-23 (annotated)

Committer:
nguyenhoang9x5555
Date:
Tue Jun 23 07:26:42 2020 +0000
Revision:
183:16414698889c
Parent:
133:05a58ba6d281 
phienbanthunghiem

Who changed what in which revision?

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