MTSCircularBuffer.h

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