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 © 2017 AT&T Intellectual Property. All rights reserved.
  12  *
  13  * Licensed under the Apache License, Version 2.0 (the "License");
  14  * you may not use this file except in compliance with the License.
  15  * You may obtain a copy of the License at
  16  *        http://www.apache.org/licenses/LICENSE-2.0
  17  *
  18  * Unless required by applicable law or agreed to in writing, software
  19  * distributed under the License is distributed on an "AS IS" BASIS,
  20  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  21  * See the License for the specific language governing permissions and
  22  * limitations under the License.
  23  *****************************************************************************/
  24
  25 #include <pthread.h>
  26
  27 /**************************************************************************//**
  28  * Ring buffer structure.
  29  *****************************************************************************/
  30 typedef struct ring_buffer
  31 {
  32     int size;
  33     int next_write;
  34     int next_read;
  35     void ** ring;
  36     pthread_cond_t ring_cv;
  37     pthread_mutex_t ring_mutex;
  38 } ring_buffer;
  39
  40 /**************************************************************************//**
  41  * Ring buffer initialization.
  42  *
  43  * Initialize the buffer supplied to the specified size.
  44  *
  45  * @param   buffer  Pointer to the ring-buffer to be initialized.
  46  * @param   size    How many elements to be stored in the ring-buffer.
  47  *
  48  * @returns Nothing
  49 ******************************************************************************/
  50 void ring_buffer_initialize(ring_buffer * buffer, int size);
  51
  52 /**************************************************************************//**
  53  * Read an element from a ring_buffer.
  54  *
  55  * Reads an element from the ring_buffer, advancing the next-read position.
  56  * Operation is synchronized and therefore MT-safe.  Blocks if no data is
  57  * available.
  58  *
  59  * @param   buffer  Pointer to the ring-buffer to be read.
  60  *
  61  * @returns Pointer to the element read from the buffer.
  62 ******************************************************************************/
  63 void * ring_buffer_read(ring_buffer * buffer);
  64
  65 /**************************************************************************//**
  66  * Write an element into a ring_buffer.
  67  *
  68  * Writes an element into the ring_buffer, advancing the next-write position.
  69  * Operation is synchronized and therefore MT-safe.  Fails if the buffer is
  70  * full without blocking.
  71  *
  72  * @param   buffer  Pointer to the ring-buffer to be written.
  73  * @param   msg     Pointer to data to be stored in the ring_buffer.
  74  *
  75  * @returns Number of items written.
  76  * @retval  1       The data was written successfully.
  77  * @retval  0       The ring_buffer was full so no data written.
  78 ******************************************************************************/
  79 int ring_buffer_write(ring_buffer * buffer, void * msg);
  80
  81 /**************************************************************************//**
  82  * Tests whether there is data in the ring_buffer.
  83  *
  84  * Tests whether there is currently data in the ring_buffer without blocking.
  85  *
  86  * @param   buffer  Pointer to the ring-buffer to be tested.
  87  *
  88  * @returns Whether there is data in the ring_buffer.
  89  * @retval  0       There isn't any data in the ring_buffer.
  90  * @retval  1       There is data in the ring_buffer.
  91 ******************************************************************************/
  92 int ring_buffer_is_empty(ring_buffer * buffer);
  93
  94 #endif