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