Stm_common/stm32 环形缓冲/ringbuffer.h

#include <inttypes.h>
#include <stddef.h>
#include <assert.h>
/**
 * @file
 * 环形缓冲模块的原型和结构。
 */

#ifndef RINGBUFFER_H
#define RINGBUFFER_H

#ifdef __cplusplus
extern "C"
{
#endif

#define RING_BUFFER_ASSERT(x) assert(x)
#define inline __inline

/**
 * 检查 buffer_size 是否为 2 的幂。
 * 由于设计仅 <tt> RING_BUFFER_SIZE-1 </tt> 项目
 * 可以包含在缓冲区中。
 * buffer_size 必须是 2 的幂。
*/
// 移除
// #define RING_BUFFER_IS_POWER_OF_TWO（buffer_size） （（buffer_size & （buffer_size - 1）） == 0）


/**
 * 用于保存大小的类型
 * 和缓冲区的指示。
 */
typedef size_t ring_buffer_size_t;

/**
 * 用作模运算符
 * 作为 <tt> a % b = （a & （b ？ 1）） </tt>
 * 其中 \c a 是缓冲区中的正索引，
 * \c b 是缓冲区的 （2 的幂） 大小。
 */
// 移除
// #define RING_BUFFER_MASK(rb) (rb->buffer_mask)

/**
 * 简化了 <tt>struct ring_buffer_t</tt> 的使用。
 */
typedef struct ring_buffer_t ring_buffer_t;

/**
 * 保存环形缓冲区的结构。
 * 缓冲区包含一个缓冲区数组
 * 以及 Ring Buffer 的元数据。
 */
struct ring_buffer_t {
  /** 缓冲内存。 */
  char *buffer;
  /** 缓冲区大小。 */
  ring_buffer_size_t buf_size;
  /** 尾巴索引。 */
  ring_buffer_size_t tail_index;
  /** 头部索引。 */
  ring_buffer_size_t head_index;
  /** 计数掩码。 */
  ring_buffer_size_t count;
};

/**
 * 初始化<em>缓冲区</em>指向的环形缓冲区。
 * 此功能也可用于清空/重置缓冲区。
 * @param buffer 要初始化的环形缓冲区。
 * @param buf 为 ringbuffer 分配的缓冲区。
 * @param buf_size 分配的 ringbuffer 的大小。
 */
void ring_buffer_init(ring_buffer_t *buffer, char *buf, size_t buf_size);

/**
 * 向环形缓冲区添加一个字节。
 * @param buffer （ 缓冲区） 应放置数据的缓冲区。
 * @param data 要放置的字节。
 */
void ring_buffer_queue(ring_buffer_t *buffer, char data);

/**
 * 将字节数组添加到环形缓冲区。
 * @param buffer （ 缓冲区） 应放置数据的缓冲区。
 * @param data 指向要放置在队列中的字节数组的指针。
 * @param size 数组的大小。
 */
void ring_buffer_queue_arr(ring_buffer_t *buffer, const char *data, ring_buffer_size_t size);

/**
 * 返回环形缓冲区中最早的字节。
 * @param buffer 应从中返回数据的缓冲区。
 * @param data 指向数据应放置位置的指针。
 * 如果返回数据，则@return 1;否则为 0。
 */
uint8_t ring_buffer_dequeue(ring_buffer_t *buffer, char *data);

/**
 * 返回环形缓冲区中 <em>len</em> 最早的字节。
 * @param buffer 应从中返回数据的缓冲区。
 * @param data 指向应放置数据的数组的指针。
 * @param len 要返回的最大字节数。
 * @return 返回的字节数。
 */
ring_buffer_size_t ring_buffer_dequeue_arr(ring_buffer_t *buffer, char *data, ring_buffer_size_t len);
/**
 * Peeks a ring buffer，即返回一个元素而不删除它。
 * @param buffer 应从中返回数据的缓冲区。
 * @param data 指向数据应放置位置的指针。
 * @param index 要速览的索引。
 * 如果返回数据，则@return 1;否则为 0。
 */
uint8_t ring_buffer_peek(ring_buffer_t *buffer, char *data, ring_buffer_size_t index);


/**
 * 返回 ring buffer 是否为空。
 * @param buffer 无论是否为空，都应该返回的缓冲区。
 * @return 1 为空;否则为 0。
 */
inline uint8_t ring_buffer_is_empty(ring_buffer_t *buffer);

/**
 * 返回环形缓冲区是否已满。
 * @param buffer 缓冲区 无论缓冲区是否已满，都应返回其缓冲区。
 * @return 1 如果已满;否则为 0。
 */
inline uint8_t ring_buffer_is_full(ring_buffer_t *buffer);

/**
 * 返回环形缓冲区中的项数。
 * @param buffer 应为其返回项目数的缓冲区。
 * @return 环形缓冲区中的项数。
 */
inline ring_buffer_size_t ring_buffer_num_items(ring_buffer_t *buffer);

#ifdef __cplusplus
}
#endif

#endif /* RINGBUFFER_H */