Thing Innovations / libmDot

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of libmDot by MultiTech

MTSCircularBuffer.h@1:9f30fbe9e9c1, 2015-06-24 (annotated)

Committer:
Mike Fiore
Date:
Wed Jun 24 17:03:08 2015 -0500
Revision:
1:9f30fbe9e9c1
add README, LICENSE, headers, and library - from git tag mbed_24June2015

Who changed what in which revision?

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