解説

SFURingBuffer は、 リングバッファを表すクラスです。 下の図をご覧ください。

リングバッファとは、 (概念上) 環状に配置されたメモリのことです。 その上を右回りに進む書き込みポインタと読み取りポインタがあります。 リングバッファにデータを書き込むと、書き込みポインタが進みます。 読み取りポインタは、書き込みポインタで書き込まれた位置までしか読み取ることができません。 また、書き込みポインタは一周を超えて書き込むことはできませんので、 書き込み操作により読み取りポインタを通り越すことはできません。

環状に配置されたメモリのサイズは固定であり、 Allocate 関数により割り当てます。 一度割り当てたメモリのサイズを、後で変更することはできません。

データの書き込みは Write で行います。 データの読み取りは Read で行います。

割り当てられているメモリのサイズは、 GetSize で取得できます。 現在書き込み可能なサイズは、 GetWritableSize で取得できます。 現在読み取り可能なサイズは、 GetReadableSize で取得できます。

割り当てられたメモリは、デストラクタにより自動的に解放されますが、 Free により明示的にメモリを解放することもできます。 Free を呼び出した後で Allocateを再度呼び出せば、 リングバッファのサイズを変更することができますが、 以前に書き込まれたデータは失われます。

リングバッファ クラスが内部で使用している書き込みポインタや読み取りポインタ を直接使用したい場合は、 LockWrite、 UnlockWrite、 LockRead、 UnlockRead を使用してください。

使用例

UInt32 wsize, rsize;

// リングバッファのインスタンスを作成します。
SFURingBuffer ring;

// 256 byte のメモリを割り当てます。      
ring.Allocate(256);
      
// メモリ割り当て直後はバッファの内容は空なので
// 書き込み可能なサイズは wsize = 256 となります。      
wsize = ring.GetWritableSize();  

// メモリ割り当て直後は、読み取り可能なデータはありません。r
// size = 0 となります。
rsize = ring.GetReadableSize();

// 4 byte のデータを書き込みます。
SInt32 n = 123;
ring.Write(&n, sizeof(n));

// 4 byte 書き込んだので、
// 残りの書き込み可能なサイズは wsize = 256 - 4 となります。
wsize = ring.GetWritableSize();

// 4 byte 書き込んだので、
// 読み取り可能なサイズは rsize = 4 となります。
rsize = ring.GetReadableSize();  

// 4 byte のデータを読み取ります。
SInt32 m;
ring.Read(&m, sizeof(m));

if (n == m) {
  // OK
}     

メンバ

解説

初期化を行います。 コンストラクタはバッファ メモリの割り当ては行いません。 バッファ メモリの割り当てを行うには、 Allocate を使用してください。

参照

SFURingBuffer::Allocate

解説

バッファ メモリが割り当てられている場合は、 自動的に Free を呼び出して、バッファ メモリを解放します。

参照

SFURingBuffer::Free

解説

バッファ メモリの割り当てを行います。 メモリ不足により割り当てが失敗すると FALSE を返します。 割り当てに成功すると TRUE を返します。

コンストラクタを呼び出した後は、 必ずこの関数でバッファ メモリを割り当ててください。 割り当てを行わずに他の関数を呼び出した場合の挙動は未定義です。

参照

SFURingBuffer::Free

解説

Allocate により割り当てられたバッファ メモリを解放します。 割り当てられていない場合は何も行いません。

参照

SFURingBuffer::Allocate

参照

SFURingBuffer::GetWritableSize

解説

リングバッファの特性から、 GetSize = GetWritableSize + GetReadableSize となります。

参照

SFURingBuffer::GetReadableSize

解説

内部で割り当てられているバッファ メモリ上の読み取りポインタを返します。 このポインタを使用して、内部バッファから直接データを読み取ることができます。 readableSize には、取得した読み取りポインタで読み取り可能なサイズが返ります。 このサイズは GetReadableSize で返されるサイズと一致するとは限らず、一般にそれ以下の値になります。

LockRead で読み取りポインタを取得した後は、 必ず UnlockRead を呼び出してください。 また、LockRead を呼び出してから UnlockRead を呼び出すまでの間に、 SFURingBuffer オブジェクトの他のメンバ関数を呼び出してはいけません。

LockRead を使用して GetReadableSize で返されるサイズだけ読み取りを行いたい場合は、 LockRead, UnlockRead を複数回呼び出してください。

使用例

下記の関数は、リングバッファから読み取り可能なデータを、 すべてファイルストリームに出力します。

Void WriteRingBufferToFile(SFUFileStreamRef file, SFURingBufferRef ring)
{
    UInt32 totalSize;

    totalSize = ring.GetReadableSize();
    while (totalSize > 0) {
        UInt32 readableSize;
        VoidPtr readPtr;
 
        readPtr = ring.LockRead(&readableSize);
        file.Put(readPtr, readableSize);
        ring.UnlockRead(readPtr, readableSize);

        totalSize -= readableSize;
    }
}

参照

SFURingBuffer::UnlockRead

解説

内部で割り当てられているバッファ メモリ上の書き込みポインタを返します。 このポインタを使用して、内部バッファに直接データを書き込みことができます。 writableSize には、取得した書き込みポインタで書き込み可能なサイズが返ります。 このサイズは GetWritableSize で返されるサイズと一致するとは限らず、一般にそれ以下の値になります。

LockWrite で書き込みポインタを取得した後は、 必ず UnlockWrite を呼び出してください。 また、LockWrite を呼び出してから UnlockWrite を呼び出すまでの間に、 SFURingBuffer オブジェクトの他のメンバ関数を呼び出してはいけません。

LockWrite を使用して GetWritableSize で返されるサイズだけ書き込みを行いたい場合は、 LockWrite, UnlockWrite を複数回呼び出してください。

使用例

下記の関数は、 ファイルストリームからデータを読み取って、 リングバッファに書き込めるだけ書き込みます。

Void WriteRingBufferFromFile(SFUFileStreamRef file, SFURingBufferRef ring)
{
    UInt32 totalSize;  // リングバッファに書き込み可能な総サイズ
    UInt32 availSize;  // ファイルから読み取り可能な総サイズ

    totalSize = ring.GetWritableSize();
    availSize = file.Available();

    while (totalSize > 0 && availSize > 0) {
        UInt32 writableSize;
        VoidPtr writePtr;
        UInt32 writtenSize;  // 実際に書き込んだサイズ
 
        writePtr = ring.LockWrite(&writableSize);
        {
            writtenSize = MIN(availSize, writableSize);
            file.Get(writePtr, writtenSize);
        }
        ring.UnlockRead(readPtr, readableSize);

        totalSize -= writtenSize;
        availSize -= writtenSize;
    }
}

参照

SFURingBuffer::UnlockWrite

解説

読み取りに成功すると TRUE を返します。 指定されたサイズだけ読み取ることができない場合は FALSE を返します。

参照

SFURingBuffer::Write

解説

書き込まれたデータをクリアします。 その結果、書き込みポインタと読み取りポインタが一致するようになり、 読み取り可能なサイズは 0 になり、 書き込み可能なサイズはバッファ サイズに等しくなります。

参照

SFURingBuffer::GetReadableSize | SFURingBuffer::GetWritableSize

解説

この関数は、 LockRead でロックした読み取りポインタをアンロックし、 読み取りポインタを readSize だけ進めます。 readSize は LockRead で取得した読み取り可能サイズ以下の値でなければなりません。

LockRead を呼び出した後は、必ずこの UnlcokRead を呼び出してください。 アンロックするまでは他のメンバ関数を呼び出してはいけません。

参照

SFURingBuffer::LockRead

解説

この関数は、 LockWrite でロックした書き込みポインタをアンロックし、 書き込みポインタを writtenSize だけ進めます。 writtenSize は LockWrite で取得した書き込み可能サイズ以下の値でなければなりません。

LockWrite を呼び出した後は、必ずこの UnlcokWrite を呼び出してください。 アンロックするまでは他のメンバ関数を呼び出してはいけません。

参照

SFURingBuffer::LockWrite

解説

書き込みに成功すると TRUE を返します。 指定されたサイズだけ書き込むことができない場合は FALSE を返します。

参照

SFURingBuffer::Read