buff分析

1. 位置

使用时包含头文件：

#include "buffer.h"

2. 数据结构

2.1. struct buffer

struct buffer

/* 缓存头 */
struct buffer
{
  struct buffer_bucket *head; /* 指向第一个数据块头 */
  struct buffer_bucket *tail; /* 指向最后一个数据块头 */
  u_int32_t alloc;     /* 已分配的数据块个数 */
  u_int32_t size;      /* 数据块的数据域大小 */
  struct buffer_bucket *unused_head; /* 未使用 */
  struct buffer_bucket *unused_tail; /* 未使用 */
  u_int32_t length;    /* 实际数据总长度 */
}; 

struct buffer_bucket2.2. struct buffer_bucket

/* 数据块头 */
struct buffer_bucket
{
  struct buffer *parent;  /* 未使用 */
  struct buffer_bucket *next;
  struct buffer_bucket *prev;
  u_char *data;  /* 数据域指针 */
  u_int32_t cp;  /* 写位置（current pointer） */
  u_int32_t sp;  /* 读位置（start pointer） */
};

3. 设计思路
· 缓存头：即struct buffer，用来管理数据块。

· 数据块：由数据块头和数据域组成。

· 数据块头：即struct buffer_bucket，以双向链表组织。

· 数据域：size大小的一块内存。

· 数据：各数据域中的有效部分（sp与cp之间的部分）。

· 缓存：由缓存头和n个数据块组成（n ≥ 0）。

· 数据块的写位置和读位置会随读写操作发生改变。

· data+sp表示数据块的读指针；data+cp表示数据块的写指针；如果cp的值为size，表示该数据块已经写满。

· 写数据时，往最后一个数据块的数据域中追加数据（从cp的位置）；如果使用完，将自动以固定大小（缓存头中的size）分配数据块并继续追加。

· 读数据时，从第一个数据块的数据域中开始读取（从sp的位置）；将读取的数据写入一个指定fd中，已被完全读取的数据块将被释放。

· 缓存示意图：

4. 接口

4.1. 缓存管理接口

4.1.1. buffer_new

· 原型
     struct buffer *buffer_new (u_int32_t size)

· 功能
     创建一个缓存头并初始化。

· 参数
     size：数据块的大小

· 返回
     非NULL：缓存头指针
     NULL：申请空间失败

4.1.2. buffer_free

· 原型

     void buffer_free (struct buffer *b)  

· 功能

     释放所有数据块，然后释放缓存。

· 参数

     b：缓存头指针 

4.1.3. buffer_empty

· 原型

     int buffer_empty (struct buffer *b)  

· 功能

     判断一个缓存是否为空。

· 参数

     b：缓存头指针

· 返回

     1：缓存为空（缓存中没有数据块，或数据块中没有数据）

     0：缓存不为空

4.1.4. buffer_reset

· 原型

     void buffer_reset (struct buffer *b)  

· 功能

     清空一个缓存（释放所有数据块）。

· 参数

     b：缓存头指针

4.1.5. buffer_add

· 原型

     struct buffer_bucket *buffer_add (struct buffer *b) 

· 功能

     分配一个数据块，并添加到缓存尾部。

· 参数

     b：缓存头指针

· 返回

     非NULL：新数据块指针
     NULL：申请空间失败

· 说明
     写数据前不需要调用此函数，因为写入数据时，会根据需求动态添加数据块。
     可改为static类型。

4.2. 数据操作接口

4.2.1. buffer_write

· 原型

     u_int32_t buffer_write (struct buffer *b, const char *ptr, u_int32_t size)  

· 功能

     向缓存中写入指定大小的数据。

· 参数

     b：缓存头指针
     ptr：源数据指针

     size：要写入的字节数

· 返回
     实际写入的字节数

· 说明
     如果数据块不够，该函数内部会动态添加（可能会添加失败）。

4.2.2. buffer_putc

· 原型

     u_int32_t buffer_putc (struct buffer *b, char c) 

· 功能

     向缓存中写入一个字符。

· 参数

     b：缓存头指针
     c：字符

· 返回

     1：写入成功
     0：写入失败

· 说明
     该函数实际调用的是buffer_write函数。

4.2.3. buffer_flush_all

· 原型

     int buffer_flush_all (struct buffer *b, pal_sock_handle_t fd)  

· 功能

     把缓存中的数据写入指定fd，然后调用buffer_reset清空缓存。

· 参数

     b：缓存头指针
     fd：文件描述符

· 返回
     大于或等于0：实际写入的字节数（fd非法也返回0）
     -1：为iovec分配空间失败

· 说明

     内部使用了iovec结构体和数据块建立一对一的映射，通过pal_sock_writevec实现输出。

     pal_sock_writevec是对writev函数的重命名，writev原型：ssize_t writev(int filedes, const struct iovec *iov, int iovcnt);
     writev以顺序iov[0]至iov[iovcnt-1]从缓冲区中聚集输出数据。writev返回输出的字节总数。

4.2.4. buffer_flush_vty

· 原型

     int buffer_flush_vty (struct buffer *b, pal_sock_handle_t fd, int size, 

                                 int erase_flag, int no_more_flag, int force_more) 

· 功能

     把缓存中的数据写入指定fd，然后释放数据已全部输出的数据块。

· 参数

     b：缓存头指针
     fd：文件描述符

     size：要写入的字节
     erase_flag：是否输出擦除状态提示信息标志（1：输出；0：不输出）

     no_more_flag：如果缓存中还有数据，是否输出字符串“--More--”（1：不输出；0：输出）
     force_more：如果值为1，则必定输出字符串“--More--”（优先级高于no_more_flag）

· 返回

     参数force_more的值

· 说明
     擦除信息字符串和字符串“--More--”各会占用一个iovec,使iov_index的值加1，一次允许输出的最大数据块个数由宏IOV_MAX决定。
     该函数是给buffer_flush_window调用的，可改为static类型。

4.2.5. buffer_flush_window

· 原型

     int buffer_flush_window (struct vty *vty, struct buffer *b, pal_sock_handle_t fd,
                                               int width, int height, int erase, int no_more)  

· 功能

     根据窗口大小输出数据到指定fd，然后释放数据已全部输出的数据块。

· 参数

     vty：虚拟终端指针
     b：缓存头指针
     fd：文件描述符
     width：窗口的宽（行宽）

     height：窗口的高（行数）

     erase：是否输出擦除状态提示信息标志（1：输出；0：不输出）
     no_more：如果缓存中还有数据，是否输出字符串“--More--”（1：不输出；0：输出）

· 返回
     1：缓存中还有数据
     0：缓存中数据已全部输出

· 说明
     该函数最终调用的是buffer_flush_vty函数。

5. 使用方法

1. 创建缓存：调用buffer_new创建一个缓存头。

2. 写入数据：

a. 调用buffer_write写入指定大小的数据。

b. 调用buffer_putc写入一个字符。

3. 输出数据：

a. 调用buffer_flush_all输出全部数据，同时清空缓存;

b. 调用buffer_flush_window在指定大小的窗口中输出buffer中的数据，同时释放数据已完全输出的数据块。

4. 释放缓存：调用buffer_free释放所有数据块及缓存头。

6. 示例

buffer_demo.c

#include "buffer.h"
 
#define BUFFER_SIZE   32
 
int main(char argc, char **argv)
{
  struct buffer *b;
  struct vty v;
  int i, ret, fd, w_bytes;
  char str[2][64] = {"hello world!\n", 
                     "buffer example program.\n"};
   
  /* 创建一个缓存头并初始化 */
  b = buffer_new(BUFFER_SIZE);
  if (NULL == b) 
    {
      return -1;
    }
 
  /* 向缓存中写入指定大小的数据 */
  for (i = 0; i < 4; i++)
    {
      w_bytes = buffer_write(b, str[i%2], strlen(str[i%2]));
      printf("%d bytes data has been written.\n", w_bytes);
    }
 
  /* 根据窗口大小输出数据到指定fd中 */
  fd = 0;
  do
    {
      ret = buffer_flush_window(&v, b, fd, 10, 8, 0, 0);
    } while(ret);
     
  return 0;
}
 
/*
  写入数据时，分配了3个数据块。
    第1个数据块中的内容为: hello world!\nbuffer example prog
    第2个数据块中的内容为: ram.\nhello world!\nbuffer example
    第3个数据块中的内容为:  program.\n
  读取数据时，指定窗口大小为10*8，输出到窗口的效果如下:
    hello worl
    d!
    buffer exa
    mple progr
    am.
    hello worl
    d!
     --More--
    buffer exa
    mple progr
    am.
 */