Revision 3:7ef4c240d5e3, committed 2012-01-31

Comitter:

JonFreeman

Date:

Tue Jan 31 09:56:38 2012 +0000

Parent:

2:7f104b72b5eb

Commit message:

Rev3a, still learning how to document nicely

Changed in this revision

diff -r 7f104b72b5eb -r 7ef4c240d5e3 circular_buffer.h
--- a/circular_buffer.h	Mon Jan 30 22:17:58 2012 +0000
+++ b/circular_buffer.h	Tue Jan 31 09:56:38 2012 +0000
@@ -9,17 +9,34 @@
 /** Classes circular_buffer_f and circular_buffer_c
 *
 *   Example use:-
+* @code
+* #include "mbed.h"
+* #include "circular_buffer.h"
+*  Serial pc(USBTX, USBRX); // Comms to Tera Term on pc
+*  Serial gizmo(p28, p27); //  Serial port for gizmo on pins 27, 28
+*  circular_buffer_c   chatter;   //  create  instance of circular_buffer_c for chars
 *
-*   circular_buffer_f   readings;   //  create  instance of circular_buffer_f
+* void    Rx_divert (void)  {          //  Gets attached to Serial::RxIrq interrupt handler
+*    while   (gizmo.readable())         //  diverting rec'd chars into purpose provided,
+*        chatter.write(gizmo.getc()); //  sufficiently sized, circular buffer
+* }
 *
 *   main    ()  {
-*   float buff[BUF_SIZE];           //  allocate memory for circular buffer_f
+*   char buff[BUF_SIZE];           //  allocate memory for circular buffer_c
+*   char x;
 *       //  Use init function to initialise (no constructor functions here)
-*   readings.init(BUF_SIZE, buff, SEEK_ENABLE | OVERWRITE_ENABLE);
-*   //  readings buffer now ready to use
-*   //  
+*   chatter.init(BUF_SIZE, buff, SEEK_ENABLE | OVERWRITE_ENABLE);
+*
+*   gizmo.attach   (Rx_divert, Serial::RxIrq); //  gizmo rx now diverted to circ buff
+*   //  serial_in buffer now ready to use
+*   while   (1) {
+*       if  (chatter.readable())    {
+*           chatter.read(&x);
+*           pc.putc(x);
+*       }
 *   }
-*    buffstart to point to start of memory allocated elsewhere through malloc, float num[SIZE] etc.
+*  }
+* @endcode
 */
 class circular_buffer_f   {     //  Circular buffer of floats
     float   *buffbase, *Onbuff, *Offbuff, *buffend;
@@ -29,28 +46,33 @@
             seek_enable;        // To allow read pointer repositioning 'n' behind current newest
     public:
 
-/** readable() returns true if stuff is in buffer to be read
-*   writeable() returns true if space exists in buffer to write more
+/** Returns true if stuff is in buffer to be read
+*
 */
     bool    readable    ()  {return !emptyf;}
+
+/** Returns true if space exists in buffer to write more
+*
+*/
     bool    writeable   ()  {return !fullf;}
     
-/** init used to setup buffer size, buffer mem address, and flaged options
-*
+/** Use init to setup buffer size, buffer mem address, and OVERWRITE_ENABLE and SEEK_ENABLE flags
+*  If OVERWRITE_ENABLE is set, allows new data to overwrite old, unread data.
+*  If OVERWRITE_ENABLE is clear, writes to a full buffer return false and new data is lost
 */
     void    init    (int size, float *buffstart, int flags);  // Size and address of buffer to work with
 
-/** Set read pointer to some distance_back in prep for multiple read using get_samps
+/** If SEEK_ENABLE flag set, sets read pointer to some distance_back in prep for multiple read using get_samps
 *
 */
     bool    seek    (int distance_back) ;   // Assumes at least that much has been written to buff beforehand
 
-/** Write places one sample into buffer
+/** Write places one sample into buffer. Returns false if buffer already full, true otherwise
 *
 */
     bool    write   (float a)  ;     // Put value into circular buffer
 
-/** Read one sample out from buffer
+/** Read one sample out from buffer. Returns false if nothing to be read, true otherwise
 *
 */
     bool    read    (float *rd)  ;