Circular Buffer

(2016.2.15 Created)

　Circular BufferとはRing Bufferや循環バッファとも呼ばれるもので、ソフトでFIFO構造を作成する一手段です。ここではSTM32のUARTライブラリで使用しています。

Circular Buffer (Ring Buffer) is a way to create FIFO structure by software. In this site, the buffer is used in STM32 UART library.

　Circularバッファとは通常1次元として説明される配列に対して、仮想的に先頭と最後を円状につなげ右図のような円環状のバッファとするものです。

　当然バッファサイズ以上のデータを書き込むと最初のデータから上書きされてしまうのですが、実際の配列の終端を意識する必要がないため、順番に処理を行う通信などでよく用いられているようです。

The circular buffer is constructed by connecting the first and the last memory, and the concept is shown in the figure.

In the case of putting data more than buffer size, the data will be overwritten. However, it seems to be often used in sequential process like communication, because it does not need to care the end of the address.

Download

　こちらからダウンロードできるDKSlib_Base.zip内にDKS_CircularBuffer.hが入っています。

You can download here. It is in the DKS_Base.zip.

使用例 / Code Example

#include "DKS_CircularBuffer.h"

int main()
{
    DKS::CircularBuffer<uint8_t, 64> cbuf;
      // Create 64byte 8bit circular buffer. 

    cbuf.push_back(0x01);    //Add value (0x01)
    cbuf.push_back(0x02);    //Add value (0x02)

    uint8_t res1 = cbuf.pull();    // Read value (0x01)
    uint8_t res2 = cbuf.pull();    // 0x02
}

Function Reference

　標準的なC++のテンプレートクラスとして作成していますので、マイコン/パソコンの種類を問わず使用していただけると思います。

This class is constructed as the standard C++ template class. It can be used by any MCU or PC.

コンストラクタ / Constructor
Declaration	CircularBuffer<typename T, uint16_t Capacity>()
Return	なし / None
Parameter	T	バッファを構成する型。例) uint8_t, int32_t ... Types of buffer.
	Capacity	バッファサイズ。２のべき乗が必要です。 Buffer size. It must be a power of 2.
Remarks	なし / None

前方に値を追加 / Add value(s) to the front.
Declaration	void push_front(const T &value) void push_front(const T* src, const uint16_t &length)
Return	なし / None
Parameter	value	追加する値。 / Value(s) to add
	length	追加するサイズ。 / Size to add
Remarks	なし / None

前方の値を削除 / Delete value(s) from the front.
Declaration	void pop_front() void pop_front(const uint16_t &length)
Return	なし / None
Parameter	length	削除する値。 / length to delete
Remarks	ポインタ位置をずらすだけで実際の配列は変化しません。 Just move the pointer. It doesn't affect actual array.

後方の値を削除 / Delete value(s) from the back
Declaration	void pop_back() void pop_back(const uint16_t &length)
Return	なし / None
Parameter	length	削除する値。 / length to delete
Remarks	ポインタ位置をずらすだけで実際の配列は変化しません。 Just move the pointer. It doesn't affect actual array.

後方に値を追加 / Add value(s) to the back.
Declaration	void push_back(const T &value) void push_back(const T* src, const uint16_t &length)
Return	なし / None
Parameter	value	追加する値。 / Value(s) to add
	length	追加するサイズ。 / Size of values
Remarks	なし / None

C配列を取得する / Get legacy C array
Declaration	void GetArray(const uint16_t &start, const uint16_t &length, T* outArray) const; void GetArray(T* outArray) const;
Return	なし / None
Parameter	outArray	C配列 / C array 事前に領域確保が必要。 Must allocate memory before calling.
	start	コピー開始位置。m_headが0 Position to start copy. 0 means m_head
	length	コピーするサイズ Length to Copy
Remarks	start / lengthを用いず呼び出す際はCapacityサイズのoutArray配列を事前に確保してください。この関数によってバッファは変化しません。 Please allocate memory size of capacity when calling without start / length parameters. The buffer is not affected by this function.

値を取得する / Get value(s)
Declaration	T pull(); void pull(T* outArray, const uint16_t &length)
Return	値 / Value
Parameter	outArray	C配列 / C array 事前に領域確保が必要。 Must allocate memory before calling.
	length	コピーするサイズ Length to Copy
Remarks	値を戻すとともにm_tailポインターを移動させます。 Move the m_tail pointer and return the value at the same time.

保管されているサイズを返す / Get stored size
Declaration	uint16_t size() const;
Return	サイズ / Stored size
Parameter	なし / None
Remarks	なし / None

バッファ容量を返す / Get buffer capacity
Declaration	uint16_t BufferCapacity() const
Return	バッファ容量 / Buffer Capacity
Parameter	なし / None
Remarks	なし / None

初期化する / Get buffer capacity
Declaration	void clear();
Return	なし / None
Parameter	なし / None
Remarks	ポインタが0位置にリセットされます。実際のバッファは変化しません。 Reset pointer to 0 position. The buffer is not affected.

[]演算子 / Operator []
Declaration	T &operator[ ](const uint16_t &n)
Return	Value
Parameter	m_headからの位置 / position from m_head
Remarks	実際のバッファは変化しません。 The buffer is not affected.