高效的两段式循环缓冲区──BipBuffer

4 The Advantages of the Circular Buffer 使用循环缓冲区的优点
There are a number of key advantages to using a circular buffer for the temporary storage of data.When one puts data into a block of memory, one also has to take it out again to make use of it. (Or one can use it in place). It is useful to be able to make use of the data in the buffer while more data is being appended to the buffer. However, as one frees up space at the head of the buffer, that space is no longer usable, unless one copies all of the data in the buffer which has not yet been used to the beginning of the buffer. This frees up space at the end of the buffer, allowing more data to be appended.
使用循环缓冲区存储临时数据的优点不可胜数。当开发者把数据存入一块临时缓冲区以后，他一定会在什么时候为了使用这个数据而把数据读取出来（或者直接使用 临时缓冲区中的数据）。在缓冲区中直接操作和使用数据的同时，缓冲区需要支持继续向数据末尾追加数据，这个特性是非常有用的。但是在通常情况下，缓冲区前 面部分的数据一旦被释放，这部分缓冲区就不再可用，除非把缓冲区后部的所有没有用到的数据都向前移动到缓冲区的起始位置。

There are a couple of ways around this; one can simply copy the data (which is a reasonably expensive proposition), or one can extend the buffer to allow more data to be appended (a massively expensive process).With a circular buffer, the free space in the buffer is always available to have data appended into it; the data is copied, the pointer adjusted, and that‘s that. No copying, no reallocation, no worries. The buffer is allocated once, and then remains useful for its entire life.
围绕着临时缓冲区的使用方法，有很多种不同的做法；最简单的一种就是直接把数据拷贝出来使用（这当然是一种效率非常低下的做法），或者动态扩展缓冲区的长 度（这涉及到系统的内存分配和释放，是效率更加低下的做法）。而使用循环缓冲区，可以总是有可用的内存来写入数据；数据可以任意拷贝，可以直接通过指针来 对数据进行存取等等。缓冲区只需要分配一次即可在其整个生存周期中发挥作用，不需要从新分配，不需要拷贝数据（译者，这里的不需要拷贝数据是指，Bip- Buffer是支持直接用指针来写入数据的，因此不需要内存拷贝之类的操作。）

5 A Fly In The Ointment 循环缓冲区美中不足的地方
One could simply implement a circular buffer by allocating a chunk of memory, and maintaining pointers. When one walked off the end of the buffer, the pointer would be adjusted - and this operation would be reflected in every operation that is performed, whether copying data into the buffer or removing it. Length calculations are slightly more complicated than normal, but not overly so - simple inline functions take care of that problem with ease, sweeping it under the rug.
Unfortunately, most API calls don‘t believe in circular buffers. You have to pass them a single contiguous block of memory which they can access, and there is no way for you to modify their write behavior to adjust pointers when they cross the end of the buffer. So what to do? Well, this is where the Bip-Buffer comes in.

人们可以通过简单的分配一块内存，小心地维护指向其的指针来实现一个循环缓冲区。当数据写入到缓冲区的末尾的时候，应该将数据写入指针调整到缓 冲区起始，这个看似简单的操作影响到对缓冲区的所有操作，无论是把数据写入还是读出。缓冲区中已用数据的长度的计算要比往常复杂一点，效率会稍微低一点 （但是这一点可以通过inline函数很轻易地解决），可以不足为虑。

不幸的是，绝大多数的api调用是不支持循环缓冲区的，很多情况下，人们不得不为这些api传入连续的装满数据的内存区，在api函数使用这块内存区的时候是无法调整其读取或写入指针到循环缓冲区的开头的。那该如何是好？别着急，这就是Bip-Buffer存在的理由。

6 Enter The Bip-Buffer 进一步了解Bip-Buffer
If one cannot pass a circular buffer into an API function, then one needs an alternative that will work - preferably with many of the same advantages as the circular buffer. It is possible to build a circular buffer which is split into two regions - or which is bi-partite (and that‘s how you get the Bip in a Bip-Buffer). Each of the two regions move through the buffer, starting at the left and ending up at the right hand side. When one runs out of space for appending data, if there is only one region, a new one is created at the beginning (if possible). The diagram below shows how it works in more detail.

如果人们不能直接把循环缓冲区直接做为参数传入api函数，那么就需要另外一种解决方案——这种方案是一个既要拥有与循环缓冲区一样的优点，又 要没有上述缺点的方案。建立一个循环缓冲区，但是在缓冲区内部将分配的两次内存，内部维护个两个区域；或者简单地来说，将传统的为循环缓冲区分配的一块内 存分裂成两块内存缓冲区来使用，这里的分裂（bi-partite）也是Bip-Buffer前面的Bip这个缩写的由来。两块内存区都是从左往右来写入 数据的，在申请缓冲区的时候，当一个缓冲区满了，就会马上从另外一个内存区的起始地点开始写入，这样就避免了调整头指针的问题。下面的图例就明确地显示了 它是如何工作的：

The buffer starts out empty, with no regions present (figure 1). (eg. immediately after calling AllocatedBuffer)

整个缓冲区开始的时候是空的，没有分裂成两个区域（如图1所示，是调用AllocatedBuffer()函数以后的样子）

Then, when data is first put into the buffer, a single region (the ‘A‘ region) is created (figure 2). (Say, by calling Reserve followed by Commit)

然后，当第一次将数据放到缓冲区以后（如图2所示，这是调用了Commit()函数以后的样子），创建了第一个区域（图中的‘A‘区域）

Data is added to the region, extending it to the right (figure 3).

当有数据继续写入的时候，都会被追加到区域A的数据的后面，使其向右不断伸展（如图3所示）

For the first time now, we remove data from the buffer (figure 4). (see the DecommitBlock call described below)

第一次从缓冲区中读出数据的样子（如图4所示，参见下面的关于DecommitBlock()函数的说明）

This continues until the region reaches the end of the buffer (figure 4). Once more free space is available to the left of region A than to the right of it, a second region (comically named "region B") is created in that space. The choice to create a new region when more space is available on the left is made to maximize the potential free space available for use in the buffer. The upshot of all this leaves us with something which looks rather like figure 5.

这种形式的写入和读出过程会持续下去，直到区域到达了缓冲区的末尾（如图4所示）。一旦在区域A左侧的可用空闲空间要大于区域A右侧的空闲空间，第二个区域（我们叫做区域B）就被创建出来，从此以后的内存分配就从这个区域B来分配（如图5所示）。

If we now use up more of the buffer space, we end up with figure 6, with new space only being allocated from the end of region B. If we eventually allocate enough data to use up all of the free space between regions A and B (figure 7), we no longer have any usable space in the buffer, and no more reservations can be performed until we read some data out of it.
如果继续使用缓冲区的空间，我们就会看到如图6所示的样子，区域B在不断扩展，将数据追加到区域B的后面。如果用光区域B与区域A之间的空间(如图7所示)，那么就真的没有内存可分配了，直到有一些数据从循环缓冲区中读出。

If we then read more data out of the buffer (say the entire remaining contents of region A), we exhaust it entirely. At the point, as region A is completely empty, we no longer need to track two separate regions, and all of region B‘s internal data is copied over region A‘s internal data, and region B is entirely cleared. (figure 8)
如果从缓冲区中读取更多的数据出来（假设整个区域A的数据都被读取出来），我们完全把区域A中存储的数据用光了，这时候区域A就完全空了，我们就不再需要 维护两个独立的区域了，这时，区域B就获得了整个缓冲区，可以继续追加数据，同时也支持从区域B中向外读取数据了（如图8所示）。

If we read a little more data out of the buffer, we now end up with something a lot like figure 4, and the cycle continues.
如果从缓冲区中读取更多的数据（如图9所示），我们最终又会得到类似图4所示的存储区使用状态，然后继续重复4,5,6,7,8这些状态的切换，完成循环利用缓冲区。

7 Characteristics of the Bip-Buffer BipBuffer的特点
The upshot of all of this is that on average, the buffer always has the maximal amount of free space available to be used, while not requiring any data copying or reallocation to free up space at the end of the buffer.
在绝大多数场合下，BipBuffer都可以充分利用全部缓冲区资源，而且即使到了缓冲区的末尾，也不需要任何数据拷贝或重新分配存储空间来实现循环利用缓冲区。

The biggest difference from an implementation standpoint between a regular circular buffer and the Bip Buffer is the fact that it only returns contiguous blocks. With a circular buffer, you need to worry about wrapping at the end of the buffer area - which is why for example if you look at Larry Antram‘s Fast Ring Buffer implementation, you‘ll see that you pass data into the buffer as a pointer and a length, the data from which is then copied byte by byte into the buffer to take into account the wrapping at the edges.

BipBuffer与常规的循环缓冲区相比较，最大的区别在于它可以返回连续的存储区。使用常规的循环缓冲区，需要考虑如何对缓冲区的末尾进行封 装。这也是当看到Larry Antram‘s Fast Ring Buffer文章中对于循环缓冲区实现的时候，会发现需要传入数据缓冲区的指针以及数据的长度，然后数据会一个字节一个字节地拷贝到循环缓冲区中去（当然 他的这种实现是需要考虑缓冲区的边界问题的。）

Another possibility which was brought up in the bulletin board (and the person who brought it up shall remain nameless, if just because they... erm...are nameless) was that of just splitting the calls across wraps. Well, this is one way of working around the wrapping problem, but it has the unfortunate side-effect that as your buffer fills, the amount of free space which you pass out to any calls always decreases to 1 byte at the minimum - even if you‘ve got another 128kb of free space at the beginning of your buffer, at the end of it you‘re still going to have to deal with ever shrinking block sizes. The Bip-Buffer neatly sidesteps this issue by just leaving that space alone if the amount you request is larger than the remaining space at the end of the buffer. When writing networking code, this is very useful; you always want to try to receive as much data as possible, but you never can guarantee how much you‘re going to get. (For most optimal results, I‘d recommend allocating a buffer which is some multiple of your MTU size).

Yes, you are going to lose some of what would have been free space at the end of the buffer. It‘s a small price to pay for playing nicely with the API.

Use of this buffer does require that one checks twice to see if the buffer has been emptied; as one has to deal with the possibility that there are two regions currently in use. However, the flexibility and performance gains outweigh this minor inconvenience.

class BipBuffer
{
private:
    BYTE* pBuffer;
    int ixa, sza, ixb, szb, buflen, ixResrv, szResrv;

public:
    BipBuffer();

The constructor initializes the internal variables for tracking regions, and memory pointers to null; it does not allocate any memory for the buffer, in case one needs to use the class in an environment where exception handling cannot be used.

~BipBuffer();

The destructor simply frees any memory which has been allocated to the buffer.

bool AllocateBuffer(int buffersize = 4096);

AllocateBuffer allocates a buffer from virtual memory. The size of the buffer is rounded up to the nearest full page size. The function returns true if successful, or false if the buffer cannot be allocated.

void FreeBuffer();

FreeBuffer frees any memory allocated to the buffer by the call to AllocateBuffer, and releases any regions allocated within the Bip-Buffer.

bool IsInitialized() const;

IsInitialized returns true if the buffer has had memory allocated to it (by calling AllocateBuffer), or false if there is no memory allocated to the buffer.

int GetBufferSize() const;

GetBufferSize returns the total size (in bytes) of the buffer. This may be greater than the value passed into AllocateBuffer, if that value was not a multiple of the system‘s page size.

void Clear();

Clear ... well... clears the buffer. It does not free any memory allocated to the buffer; it merely resets the region pointers back to null, making the full buffer usable for new data again.

BYTE* Reserve(int size, OUT int& reserved);

Now to the nitty-gritty. Allocating data in the Bip-Buffer is a two-phase operation. First an area is reserved by calling the Reserve function; then, that area is Committed by calling the Commit function. This allows one to, say, reserve memory for an IO call, and when that IO call fails, pretend it never happened. Or alternatively, in a call to an overlapped WSARecv() function, it allows one to advertise how much memory is available to the network stack to use for incoming data, and then adjust the amount of space used based on how much data was actually read in (which may be less than the requested amount).

To use Reserve, pass in the size of block requested. The function will return the size of the largest free block available which is less than or equal tosize in length in the reserved parameter you passed in. It will also return a BYTE* pointer to the area of the buffer which you have reserved.

In the case where the buffer has no space available, Reserve will return a NULL pointer, andreserved will be set to zero.

Note: you cannot nest calls to Reserve and Commit; after calling Reserve you must call Commit before calling Reserve again.

void Commit(int size);

Here‘s the other half of the allocation. Commit takes a size parameter, which is the number of bytes (starting at the BYTE* you were passed back from Reserve) which you have actually used and want to keep in the buffer. If you pass in zero for this size, the reservation will be completely released, as if you had never reserved any space at all. Alternatively, in a debug build, if one passes in a value greater than the original reservation, an assert will fire. (In a release build, the original reservation size will be used, and no one will be any the wiser). Committing data to the buffer makes it available for routines which take data back out of the buffer.

The diagram above shows how Reserve and Commit work. When you call Reserve, it will return a pointer to the beginning of the gray area above (fig. 1). Say you then only use as much of that buffer as the blue section (fig 2). It‘d be a shame to leave this area allocated and going to waste, so you can call Commit with only as much data as you used, which gives you fig. 3 - namely, the committed space extends to fill just the part you needed, leaving the rest free.

int GetReservationSize() const;

If at any time you need to find out if you have a pending reservation, or need to find out that reservation‘s size, you can call GetReservationSize to find the amount reserved. No reservation? You‘ll get a zero back.

BYTE* GetContiguousBlock(OUT int& size);

Well, after all this work to put stuff into the buffer, we‘d better have a way of getting it out again.

First of all, what if you need to work out how much data (total) is available to be read from the buffer?

int GetCommittedSize() const;

One method is to call GetCommittedSize, which will return the total length of data in the buffer - that‘s the total size of both regions combined. I would not recommend relying on this number, because it‘s very easy to forget that you have two regions in the Bip-Buffer if you do. And that would be a bad thing (as several weeks of painful debugging experience has proved to me). As an alternative, you can call:

BYTE* GetContiguousBlock(OUT int& size);

... which will return a BYTE* pointer to the first (as in FIFO, not left-most) contiguous region of committed data in the buffer. Thesize parameter is also updated with the length of the block. If no data is available, the function returns NULL (and thesize parameter is set to zero).

In order to fully empty the buffer, you may wish to loop around, calling GetContiguousBlock until it returns NULL. If you‘re feeling miserly, you can call it only twice. However, I‘d recommend the former; it means you can forget that there‘s two regions, and just remember that there‘s more than one.

void DecommitBlock(int size);

So what do you do after you‘ve consumed data from the buffer? Well, in keeping with the spirit of the aforementioned Reserve and Commit calls, you then call DecommitBlock to release data from it. Data is released in FIFO order, from the first contiguous block only - so if you‘re going to call DecommitBlock, you should do it pretty shortly after calling GetContiguousBlock. If you pass in asize of greater than the length of the contiguous block, then the entire block is released - but none of the other block (if present) is released at all. This is a deliberate design choice to remind you that there is more than one block and you should act accordingly. (If you really need to be able to discard data from blocks you‘ve not read yet, it‘s not too difficult to copy the DecommitBlock function and modify it so that it operates on both blocks; just unwrap the if statement, and adjust the size parameter after the first clause. Implementation of this is left as the dreaded youknowwhat).

And that‘s the Bip-Buffer implementation done. A short example of how to use it is provided below.

#include "BipBuffer.h"

BipBuffer buffer;
SOCKET s;
bool read_EOF;

bool StartUp
{
    // Allocate a buffer 8192 bytes in length
    if (!buffer.AllocateBuffer(8192)) return false;
    readEOF = false;

    s = socket(...

    ... do something else ...
}

void Foo()
{
    _ASSERTE(buffer.IsValid());

    // Reserve as much space as possible in the buffer:

    int space;
    BYTE* pData = buffer.Reserve(GetBufferSize(), space);

    // We now have *space* amount of room to play with.


    if (pData == NULL) return;

    // Obviously we‘ve not emptied the buffer recently

    // because there isn‘t any room in it if we return.


    // Let‘s use the buffer!

    int recvcount = recv(s, (char*)pData, space, 0);

    if (recvcount == SOCKET_ERROR) return;
    // heh... that‘s some kind of error handling...


    // We now have data in the buffer (or, if the

    // connection was gracefully closed, we don‘t have any)


    buffer.Commit(recvcount);

    if (recvcount == 0) read_EOF = true;

}

void Bar()
{
    _ASSERTE(buffer.IsValid());

    // Let‘s empty the buffer.


    int allocated;
    BYTE* pData;

    while (pData = buffer.GetContiguousBlock(allocated)
           != NULL)
    {
        // Let‘s do something with the data.


        fwrite(pData, allocated, 1, outputfile);

        // (again, lousy error handling)


        buffer.DecommitBlock(allocated);
    }
}

代码：