环形缓冲区

环形缓冲区的基本概念

环形缓冲区的基本概念来自Wikipedia：环形缓冲器

圆形缓冲区（circular buffer），也称作圆形队列（circular queue），循环缓冲区（cyclic buffer），环形缓冲区（ring buffer），是一种用于表示一个固定尺寸、头尾相连的缓冲区的数据结构，适合缓存数据流。

圆形缓冲区的一个有用特性是：当一个数据元素被用掉后，其余数据元素不需要移动其存储位置。相反，一个非圆形缓冲区（例如一个普通的队列）在用掉一个数据元素后，其余数据元素需要向前搬移。换句话说，圆形缓冲区适合实现先进先出缓冲区，而非圆形缓冲区适合后进先出缓冲区。

圆形缓冲区适合于事先明确了缓冲区的最大容量的情形。扩展一个圆形缓冲区的容量，需要搬移其中的数据。因此一个缓冲区如果需要经常调整其容量，用链表实现更为合适。

写操作覆盖圆形缓冲区中未被处理的数据在某些情况下是允许的。特别是在多媒体处理时。例如，音频的生产者可以覆盖掉声卡尚未来得及处理的音频数据。

圆形缓冲区的实现

环形缓冲区的特点：
1. 环形缓冲区的大小是固定的，在整个过程中只申请一次内存。
2. 是一种先进先出的缓冲区。
3. 写操作时，当要写入的size大于available write size时有两种处理方式：覆盖、不覆盖（哈哈，废话），依情况选择。

我只是代码的搬运工，代码来自webrtc的ring_buffer.h，具体位置是webrtc/common_audio/ring_buffer.h。读写操作是非线程安全的，所以需要调用者自己去保证线程安全。写操作遇到要写入的大小大于可用大小时选择的方式是：部分写入的策略。所以在使用的时候不顺心可以改改改！

• 对外提供的API代码：
  是一个完全独立的功能，不依赖任何webrtc的头文件，可以脱离webrtc在任意地方使用。考虑到并非每一个人都能访问googlesource，so直接列出源码。官方-ring_buffer.h

#ifndef WEBRTC_COMMON_AUDIO_RING_BUFFER_H_#define WEBRTC_COMMON_AUDIO_RING_BUFFER_H_#ifdef __cplusplusextern "C" {#endif#include <stddef.h>  // size_ttypedef struct RingBuffer RingBuffer;// Creates and initializes the buffer. Returns NULL on failure.RingBuffer* WebRtc_CreateBuffer(size_t element_count, size_t element_size);void WebRtc_InitBuffer(RingBuffer* handle);void WebRtc_FreeBuffer(void* handle);// Reads data from the buffer. The |data_ptr| will point to the address where// it is located. If all |element_count| data are feasible to read without// buffer wrap around |data_ptr| will point to the location in the buffer.// Otherwise, the data will be copied to |data| (memory allocation done by the// user) and |data_ptr| points to the address of |data|. |data_ptr| is only// guaranteed to be valid until the next call to WebRtc_WriteBuffer().//// To force a copying to |data|, pass a NULL |data_ptr|.//// Returns number of elements read.size_t WebRtc_ReadBuffer(RingBuffer* handle,                         void** data_ptr,                         void* data,                         size_t element_count);// Writes |data| to buffer and returns the number of elements written.size_t WebRtc_WriteBuffer(RingBuffer* handle, const void* data,                          size_t element_count);// Moves the buffer read position and returns the number of elements moved.// Positive |element_count| moves the read position towards the write position,// that is, flushing the buffer. Negative |element_count| moves the read// position away from the the write position, that is, stuffing the buffer.// Returns number of elements moved.int WebRtc_MoveReadPtr(RingBuffer* handle, int element_count);// Returns number of available elements to read.size_t WebRtc_available_read(const RingBuffer* handle);// Returns number of available elements for write.size_t WebRtc_available_write(const RingBuffer* handle);#ifdef __cplusplus}#endif#endif  // WEBRTC_COMMON_AUDIO_RING_BUFFER_H_

• 实现代码：
  只依赖标准库，足够的说明，Good。官方-ring_buffer.c

#include "ring_buffer.h"#include <stddef.h>  // size_t#include <stdlib.h>#include <string.h>enum Wrap {  SAME_WRAP,  DIFF_WRAP};struct RingBuffer {  size_t read_pos;  size_t write_pos;  size_t element_count;  size_t element_size;  enum Wrap rw_wrap;  char* data;};// Get address of region(s) from which we can read data.// If the region is contiguous, |data_ptr_bytes_2| will be zero.// If non-contiguous, |data_ptr_bytes_2| will be the size in bytes of the second// region. Returns room available to be read or |element_count|, whichever is// smaller.static size_t GetBufferReadRegions(RingBuffer* buf,                                   size_t element_count,                                   void** data_ptr_1,                                   size_t* data_ptr_bytes_1,                                   void** data_ptr_2,                                   size_t* data_ptr_bytes_2) {  const size_t readable_elements = WebRtc_available_read(buf);  const size_t read_elements = (readable_elements < element_count ?      readable_elements : element_count);  const size_t margin = buf->element_count - buf->read_pos;  // Check to see if read is not contiguous.  if (read_elements > margin) {    // Write data in two blocks that wrap the buffer.    *data_ptr_1 = buf->data + buf->read_pos * buf->element_size;    *data_ptr_bytes_1 = margin * buf->element_size;    *data_ptr_2 = buf->data;    *data_ptr_bytes_2 = (read_elements - margin) * buf->element_size;  } else {    *data_ptr_1 = buf->data + buf->read_pos * buf->element_size;    *data_ptr_bytes_1 = read_elements * buf->element_size;    *data_ptr_2 = NULL;    *data_ptr_bytes_2 = 0;  }  return read_elements;}RingBuffer* WebRtc_CreateBuffer(size_t element_count, size_t element_size) {  RingBuffer* self = NULL;  if (element_count == 0 || element_size == 0) {    return NULL;  }  self = malloc(sizeof(RingBuffer));  if (!self) {    return NULL;  }  self->data = malloc(element_count * element_size);  if (!self->data) {    free(self);    self = NULL;    return NULL;  }  self->element_count = element_count;  self->element_size = element_size;  WebRtc_InitBuffer(self);  return self;}void WebRtc_InitBuffer(RingBuffer* self) {  self->read_pos = 0;  self->write_pos = 0;  self->rw_wrap = SAME_WRAP;  // Initialize buffer to zeros  memset(self->data, 0, self->element_count * self->element_size);}void WebRtc_FreeBuffer(void* handle) {  RingBuffer* self = (RingBuffer*)handle;  if (!self) {    return;  }  free(self->data);  free(self);}size_t WebRtc_ReadBuffer(RingBuffer* self,                         void** data_ptr,                         void* data,                         size_t element_count) {  if (self == NULL) {    return 0;  }  if (data == NULL) {    return 0;  }  {    void* buf_ptr_1 = NULL;    void* buf_ptr_2 = NULL;    size_t buf_ptr_bytes_1 = 0;    size_t buf_ptr_bytes_2 = 0;    const size_t read_count = GetBufferReadRegions(self,                                                   element_count,                                                   &buf_ptr_1,                                                   &buf_ptr_bytes_1,                                                   &buf_ptr_2,                                                   &buf_ptr_bytes_2);    if (buf_ptr_bytes_2 > 0) {      // We have a wrap around when reading the buffer. Copy the buffer data to      // |data| and point to it.      memcpy(data, buf_ptr_1, buf_ptr_bytes_1);      memcpy(((char*) data) + buf_ptr_bytes_1, buf_ptr_2, buf_ptr_bytes_2);      buf_ptr_1 = data;    } else if (!data_ptr) {      // No wrap, but a memcpy was requested.      memcpy(data, buf_ptr_1, buf_ptr_bytes_1);    }    if (data_ptr) {      // |buf_ptr_1| == |data| in the case of a wrap.      *data_ptr = buf_ptr_1;    }    // Update read position    WebRtc_MoveReadPtr(self, (int) read_count);    return read_count;  }}size_t WebRtc_WriteBuffer(RingBuffer* self,                          const void* data,                          size_t element_count) {  if (!self) {    return 0;  }  if (!data) {    return 0;  }  {    const size_t free_elements = WebRtc_available_write(self);    const size_t write_elements = (free_elements < element_count ? free_elements        : element_count);    size_t n = write_elements;    const size_t margin = self->element_count - self->write_pos;    if (write_elements > margin) {      // Buffer wrap around when writing.      memcpy(self->data + self->write_pos * self->element_size,             data, margin * self->element_size);      self->write_pos = 0;      n -= margin;      self->rw_wrap = DIFF_WRAP;    }    memcpy(self->data + self->write_pos * self->element_size,           ((const char*) data) + ((write_elements - n) * self->element_size),           n * self->element_size);    self->write_pos += n;    return write_elements;  }}int WebRtc_MoveReadPtr(RingBuffer* self, int element_count) {  if (!self) {    return 0;  }  {    // We need to be able to take care of negative changes, hence use "int"    // instead of "size_t".    const int free_elements = (int) WebRtc_available_write(self);    const int readable_elements = (int) WebRtc_available_read(self);    int read_pos = (int) self->read_pos;    if (element_count > readable_elements) {      element_count = readable_elements;    }    if (element_count < -free_elements) {      element_count = -free_elements;    }    read_pos += element_count;    if (read_pos > (int) self->element_count) {      // Buffer wrap around. Restart read position and wrap indicator.      read_pos -= (int) self->element_count;      self->rw_wrap = SAME_WRAP;    }    if (read_pos < 0) {      // Buffer wrap around. Restart read position and wrap indicator.      read_pos += (int) self->element_count;      self->rw_wrap = DIFF_WRAP;    }    self->read_pos = (size_t) read_pos;    return element_count;  }}size_t WebRtc_available_read(const RingBuffer* self) {  if (!self) {    return 0;  }  if (self->rw_wrap == SAME_WRAP) {    return self->write_pos - self->read_pos;  } else {    return self->element_count - self->read_pos + self->write_pos;  }}size_t WebRtc_available_write(const RingBuffer* self) {  if (!self) {    return 0;  }  return self->element_count - WebRtc_available_read(self);}

• 功能测试
  Google的代码文档少，但是必定会有测试代码，一般是Gtest的单元测试，很专业。
  ring_buffer_unittest.cc