vnfs/VES/code/evel_library/ring_buffer.h

   1 #ifndef RING_BUFFER_INCLUDED
   2 #define RING_BUFFER_INCLUDED
   3
   4 /**************************************************************************//**
   5  * @file
   6  * A ring buffer.
   7  *
   8  * License
   9  * -------
  10  *
  11  * Copyright(c) <2016>, AT&T Intellectual Property.  All other rights reserved.
  12  *
  13  * Redistribution and use in source and binary forms, with or without
  14  * modification, are permitted provided that the following conditions are met:
  15  *
  16  * 1. Redistributions of source code must retain the above copyright notice,
  17  *    this list of conditions and the following disclaimer.
  18  * 2. Redistributions in binary form must reproduce the above copyright notice,
  19  *    this list of conditions and the following disclaimer in the documentation
  20  *    and/or other materials provided with the distribution.
  21  * 3. All advertising materials mentioning features or use of this software
  22  *    must display the following acknowledgement:  This product includes
  23  *    software developed by the AT&T.
  24  * 4. Neither the name of AT&T nor the names of its contributors may be used to
  25  *    endorse or promote products derived from this software without specific
  26  *    prior written permission.
  27  *
  28  * THIS SOFTWARE IS PROVIDED BY AT&T INTELLECTUAL PROPERTY ''AS IS'' AND ANY
  29  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  30  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  31  * DISCLAIMED. IN NO EVENT SHALL AT&T INTELLECTUAL PROPERTY BE LIABLE FOR ANY
  32  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  33  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  34  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  35  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  36  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  37  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  38  *****************************************************************************/
  39
  40 #include <pthread.h>
  41
  42 /**************************************************************************//**
  43  * Ring buffer structure.
  44  *****************************************************************************/
  45 typedef struct ring_buffer
  46 {
  47     int size;
  48     int next_write;
  49     int next_read;
  50     void ** ring;
  51     pthread_cond_t ring_cv;
  52     pthread_mutex_t ring_mutex;
  53 } ring_buffer;
  54
  55 /**************************************************************************//**
  56  * Ring buffer initialization.
  57  *
  58  * Initialize the buffer supplied to the specified size.
  59  *
  60  * @param   buffer  Pointer to the ring-buffer to be initialized.
  61  * @param   size    How many elements to be stored in the ring-buffer.
  62  *
  63  * @returns Nothing
  64 ******************************************************************************/
  65 void ring_buffer_initialize(ring_buffer * buffer, int size);
  66
  67 /**************************************************************************//**
  68  * Read an element from a ring_buffer.
  69  *
  70  * Reads an element from the ring_buffer, advancing the next-read position.
  71  * Operation is synchronized and therefore MT-safe.  Blocks if no data is
  72  * available.
  73  *
  74  * @param   buffer  Pointer to the ring-buffer to be read.
  75  *
  76  * @returns Pointer to the element read from the buffer.
  77 ******************************************************************************/
  78 void * ring_buffer_read(ring_buffer * buffer);
  79
  80 /**************************************************************************//**
  81  * Write an element into a ring_buffer.
  82  *
  83  * Writes an element into the ring_buffer, advancing the next-write position.
  84  * Operation is synchronized and therefore MT-safe.  Fails if the buffer is
  85  * full without blocking.
  86  *
  87  * @param   buffer  Pointer to the ring-buffer to be written.
  88  * @param   msg     Pointer to data to be stored in the ring_buffer.
  89  *
  90  * @returns Number of items written.
  91  * @retval  1       The data was written successfully.
  92  * @retval  0       The ring_buffer was full so no data written.
  93 ******************************************************************************/
  94 int ring_buffer_write(ring_buffer * buffer, void * msg);
  95
  96 /**************************************************************************//**
  97  * Tests whether there is data in the ring_buffer.
  98  *
  99  * Tests whether there is currently data in the ring_buffer without blocking.
 100  *
 101  * @param   buffer  Pointer to the ring-buffer to be tested.
 102  *
 103  * @returns Whether there is data in the ring_buffer.
 104  * @retval  0       There isn't any data in the ring_buffer.
 105  * @retval  1       There is data in the ring_buffer.
 106 ******************************************************************************/
 107 int ring_buffer_is_empty(ring_buffer * buffer);
 108
 109 #endif