support library for C027 helper functions for Buffer Pipes, Buffered Serial Port (rtos capable) and GPS parsing. It includes modem APIs for USSD, SMS and Sockets.
Dependents: C027Interface C027Interface C027_SupportTest
Fork of C027_Support by
Diff: Pipe.h
- Revision:
- 40:295099ff5338
- Parent:
- 21:c4d64830bf02
- Child:
- 41:b94a1f410e71
--- a/Pipe.h Fri Apr 11 19:16:03 2014 +0000 +++ b/Pipe.h Fri Apr 11 19:39:08 2014 +0000 @@ -1,17 +1,18 @@ #pragma once +/** pipe, this class implements a buffered pipe that can be savely + written and read between two context. E.g. Written from a task + and read from a interrupt. +*/ template <class T> class Pipe { -private: - inline int _inc(int i, int n = 1) - { - i += n; - if (i >= _s) - i -= _s; - return i; - } public: + /* Constructor + \param n size of the pipe/buffer + \param b optional buffer that should be used. + if NULL the constructor will allocate a buffer of size n. + */ Pipe(int n, T* b = NULL) { _a = b ? NULL : new T[n]; @@ -20,11 +21,18 @@ _b = b ? b : _a; _s = n; } + /** Destructor + frees a allocated buffer. + */ virtual ~Pipe(void) { if (_a) delete [] _a; } + + /* This function can be used during debugging to hexdump the + content of a buffer to the stdout. + */ void dump(void) { int o = _r; @@ -36,18 +44,33 @@ } printf("\n"); } - // writing thread - bool writeable(void) // = not full + + // writing thread/context API + //------------------------------------------------------------- + + /** Check if buffer is writeable (=not full) + \return true if writeable + */ + bool writeable(void) { return free() > 0; } - int free(void) // number of elements that can be added + + /** Return the number of free elements in the buffer + \return the number of free elements + */ + int free(void) { int s = _r - _w; if (s <= 0) s += _s; return s - 1; } + + /* Add a single element to the buffer. (blocking) + \param c the element to add. + \return c + */ T putc(T c) { int i = _w; @@ -59,6 +82,13 @@ _w = i; return c; } + + /* Add a buffer of elements to the buffer. + \param p the elements to add + \param n the number elements to add from p + \param t set to true if blocking, false otherwise + \return number elements added + */ int put(const T* p, int n, bool t = false) { int c = n; @@ -84,14 +114,21 @@ } return n - c; } - // reading thread + + // reading thread/context API // -------------------------------------------------------- - //! check if there are any values available - bool readable(void) // = not empty + + /** Check if there are any emelemnt available (readble / not empty) + \return true if readable/not empty + */ + bool readable(void) { return (_r != _w); } - //! get the number of values avialable in the buffer + + /** Get the number of values available in the buffer + return the number of element available + */ virtual int size(void) { int s = _w - _r; @@ -99,7 +136,10 @@ s += _s; return s; } - //! get a value from buffer (this function will block if no values available) + + /** get a single value from buffered pipe (this function will block if no values available) + \return the element extracted + */ T getc(void) { int r = _r; @@ -109,7 +149,13 @@ _r = _inc(r); return t; } - //! get values from buffer + + /*! get elements from the buffered pipe + \param p the elements extracted + \param n the maximum number elements to extract + \param t set to true if blocking, false otherwise + \return number elements extracted + */ virtual int get(T* p, int n, bool t = false) { int c = n; @@ -136,9 +182,15 @@ return n - c; } - // the following functions are useful if you like to inspect or parse the buffer + // the following functions are useful if you like to inspect + // or parse the buffer in the reading thread/context + // -------------------------------------------------------- - //! reset the parsing index and return the number of available elments + /** set the parsing index and return the number of available + elments starting this position. + \param ix the index to set. + \return the number of elements starting at this position + */ virtual int set(int ix) { int sz = size(); @@ -146,7 +198,10 @@ _o = _inc(_r, ix); return sz - ix; } - //! get the next element and increment + + /** get the next element from parsing position and increment parsing index + \return the extracted element. + */ virtual T next(void) { int o = _o; @@ -154,13 +209,28 @@ _o = _inc(o); return t; } - //! commit the index + + /** commit the index, mrk the current parsing index as consumed data. + */ virtual void done(void) { _r = _o; } private: + /** increment the index + \param i index to increment + \param n the step to increment + \return the incremented index. + */ + inline int _inc(int i, int n = 1) + { + i += n; + if (i >= _s) + i -= _s; + return i; + } + T* _b; //!< buffer T* _a; //!< allocated buffer int _s; //!< size of buffer (s - 1) elements can be stored