MTSCircularBuffer.h

00001 #ifndef MTSCIRCULARBUFFER_H
00002 #define MTSCIRCULARBUFFER_H
00003 
00004 #include <Callback.h>
00005 
00006 #include "Utils.h"
00007 
00008 namespace mts
00009 {
00010 
00011 /** This class provides a circular byte buffer meant for temporary storage
00012 * during IO transactions.  It contains many of the common methods you
00013 * would expect from a circular buffer like read, write, and various
00014 * methods for checking the size or status.  It should be noted that
00015 * this class does not include any special code for thread safety like
00016 * a lock.  In most cases this is not problematic, but is something
00017 * to be aware of.
00018 */
00019 class MTSCircularBuffer
00020 {
00021 public:
00022     /** Creates an MTSCircularBuffer object with the specified static size.
00023     *
00024     * @prarm bufferSize size of the buffer in bytes.
00025     */
00026     MTSCircularBuffer(int bufferSize);
00027 
00028     /** Destructs an MTSCircularBuffer object and frees all related resources.
00029     */
00030     ~MTSCircularBuffer();
00031 
00032     /** This method enables bulk reads from the buffer.  If more data is
00033     * requested then available it simply returns all remaining data within the
00034     * buffer.
00035     *
00036     * @param data the buffer where data read will be added to.
00037     * @param length the amount of data in bytes to be read into the buffer.
00038     * @returns the total number of bytes that were read.
00039     */
00040     int read(char* data, int length);
00041 
00042     /** This method reads a single byte from the buffer.
00043     *
00044     * @param data char where the read byte will be stored.
00045     * @returns 1 if byte is read or 0 if no bytes available.
00046     */
00047     int read(char& data);
00048 
00049     /** This method enables bulk writes to the buffer. If more data
00050     * is requested to be written then space available the method writes
00051     * as much data as possible and returns the actual amount written.
00052     *
00053     * @param data the byte array to be written.
00054     * @param length the length of data to be written from the data paramter.
00055     * @returns the number of bytes written to the buffer, which is 0 if
00056     * the buffer is full.
00057     */
00058     int write(const char* data, int length);
00059 
00060     /** This method writes a signle byte as a char to the buffer.
00061     *
00062     * @param data the byte to be written as a char.
00063     * @returns 1 if the byte was written or 0 if the buffer was full.
00064     */
00065     int write(char data);
00066 
00067     /** This method is used to setup a callback funtion when the buffer reaches
00068     * a certain threshold. The threshold condition is checked after every read
00069     * and write call is completed. The condition is made up of both a threshold
00070     * value and operator. An example that would trigger a callback is if the
00071     * threshold was 10, the operator GREATER, and there were 12 bytes added to an
00072     * empty buffer.
00073     *
00074     * @param tptr a pointer to the object to be called when the condition is met.
00075     * @param mptr a pointer to the function within the object to be called when
00076     * the condition is met.
00077     * @param threshold the value in bytes to be used as part of the condition.
00078     * @param op the operator to be used in conjunction with the threshold
00079     * as part of the condition.
00080     */
00081     template<typename T>
00082     void attach(T *tptr, void( T::*mptr)(void), int threshold, RelationalOperator op) {
00083         _threshold = threshold;
00084         _op = op;
00085         notify.attach(tptr, mptr);
00086     }
00087 
00088     /** This method is used to setup a callback funtion when the buffer reaches
00089     * a certain threshold. The threshold condition is checked after every read
00090     * and write call is completed. The condition is made up of both a threshold
00091     * value and operator. An example that would trigger a callback is if the
00092     * threshold was 10, the operator GREATER, and there were 12 bytes added to an
00093     * empty buffer.
00094     *
00095     * @param fptr a pointer to the static function to be called when the condition
00096     * is met.
00097     * @param threshold the value in bytes to be used as part of the condition.
00098     * @param op the operator to be used in conjunction with the threshold
00099     * as part of the condition.
00100     */
00101     void attach(void(*fptr)(void), int threshold, RelationalOperator op) {
00102         _threshold = threshold;
00103         _op = op;
00104         notify = fptr;
00105     }
00106 
00107     /** This method returns the size of the storage space currently allocated for
00108     * the buffer. This value is equivalent to the one passed into the constructor.
00109     * This value is equal or greater than the size() of the buffer.
00110     *
00111     * @returns the allocated size of the buffer in bytes.
00112     */
00113     int capacity();
00114 
00115     /** This method returns the amount of space left for writing.
00116     *
00117     * @returns numbers of unused bytes in buffer.
00118     */
00119     int remaining();
00120 
00121     /** This method returns the number of bytes available for reading.
00122     *
00123     * @returns number of bytes currently in buffer.
00124     */
00125     int size();
00126 
00127     /** This method returns whether the buffer is full.
00128     *
00129     * @returns true if full, otherwise false.
00130     */
00131     bool isFull();
00132 
00133     /** This method returns whether the buffer is empty.
00134     *
00135     * @returns true if empty, otherwise false.
00136     */
00137     bool isEmpty();
00138 
00139     /** This method clears the buffer. This is done through
00140     * setting the internal read and write indexes to the same
00141     * value and is therefore not an expensive operation.
00142     */
00143     void clear();
00144 
00145 
00146 private:
00147     int bufferSize; // total size of the buffer
00148     char* buffer; // internal byte buffer as a character buffer
00149     int readIndex; // read index for circular buffer
00150     int writeIndex; // write index for circular buffer
00151     int bytes; // available data
00152     Callback<void()> notify; // Internal callback notification
00153     int _threshold; // threshold for the notification
00154     RelationalOperator _op; // operator that determines the direction of the threshold
00155     void checkThreshold(); // private function that checks thresholds and processes notifications
00156 };
00157 
00158 }
00159 
00160 #endif /* MTSCIRCULARBUFFER_H */