SFXRingBuffer

Class that represents a ring buffer.

#include <SFXRingBuffer.h.hpp>

class SFXRingBuffer;

SFMTYPEDEFCLASS(SFXRingBuffer)

Collaboration diagram

Description

SFXRingBuffer is a class that represents a ring buffer.

Conceptually, the ring buffer is a circular buffer. There are the write pointer and the read pointer that proceed clockwisely on the ring buffer.

After writing data on the ring buffer, the write pointer proceeds. Data can be read until the position written by the write pointer through the read pointer.

The write pointer cannot overtake the read pointer by writing data on the ring buffer.

Example

UInt32 wsize, rsize;

// create the SFXRingBuffer object
SFXRingBuffer ring;

// allocate 256 bytes of memory
ring.Allocate(256);

// since the buffer is empty just after memory allocation, 
// size of area to be written is 256, i.e. wsize = 0 
wsize = ring.GetWritableSize();

// since the buffer is empty just after memory allocation, 
// size of area to be read is 0, i.e. rsize = 0
rsize = ring.GetReadableSize();

// write 4 byte of data
SInt32 n = 123;
ring.Write(&n, sizeof(n));

// size of area to be written is 252, i.e. wsize = 252
wsize = ring.GetWritableSize();

// size of area to be read is 4, i.e. rsize = 4
rsize = ring.GetReadableSize();

// read 4 byte of data
SInt32 m;
ring.Read(&m, sizeof(m));

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

Reference

Ring Buffer

Member

Constructor/Destructor
SFXRingBuffer( `Void` ) Constructor of SFXRingBuffer class.
~SFXRingBuffer( `Void` ) Destructor of the SFXRingBuffer class.

Public Functions
`SFCError`	Allocate( `UInt32` size ) Allocate buffer memory.
static `SFXRingBufferConstRef`	EmptyInstance( `Void` ) Get an empty ring buffer.
`SInt32`	FirstIndexOf( `SFXBufferConstRef` buffer , `SInt32` index = SINT32_MINIMUM ) FirstIndexOf( `Byte` byte , `SInt32` index = SINT32_MINIMUM ) FirstIndexOf( `VoidConstPtr` buffer , `UInt32` size , `SInt32` index = SINT32_MINIMUM ) Get the first index of SFXRingBuffer object to match with the specified data, searching from the beginning.
`Void`	Free( `Void` ) Release the buffer memory that the SFXRingBuffer object manages.
`VoidConstPtr`	GetReadableBuffer( `UInt32Ptr` size ) Get the read pointer.
`UInt32`	GetReadableSize( `Void` ) Get the size of data area that can be read through the read pointer.
`UInt32`	GetSize( `Void` ) Get the size of buffer memory.
`VoidPtr`	GetWritableBuffer( `UInt32Ptr` size ) Get the write pointer.
`UInt32`	GetWritableSize( `Void` ) Get the size of data area that can be written through the write pointer.
`SInt32`	LastIndexOf( `SFXBufferConstRef` buffer , `SInt32` index = SINT32_MAXIMUM ) LastIndexOf( `Byte` byte , `SInt32` index = SINT32_MAXIMUM ) LastIndexOf( `VoidConstPtr` buffer , `UInt32` buffer , `SInt32` index = SINT32_MAXIMUM ) Get the last index of SFXRingBuffer object to match with the specified data, searching from the end.
`SFCError`	Read( `VoidPtr` buffer , `UInt32` size ) Read( `SFXBufferPtr` buffer ) Read data.
`Void`	Reset( `Void` ) Clear the written data.
`SFCError`	SeekRead( `UInt32` size ) Set forward the read pointer.
`SFCError`	SeekWrite( `UInt32` size ) Set forward the write pointer.
`SFCError`	Write( `VoidConstPtr` buffer , `UInt32` size ) Write( `SFXBufferConstRef` buffer ) Write data.

SFXRingBuffer::SFXRingBuffer

Constructor of SFXRingBuffer class.

[ public, explicit ]
SFXRingBuffer(Void);

Description

Since memory is not allocated for the ring buffer in the constructor, it is necessary to call the SFXRingBuffer::Allocate function.

Reference

SFXRingBuffer::Allocate

SFXRingBuffer::~SFXRingBuffer

Destructor of the SFXRingBuffer class.

[ public ]
~SFXRingBuffer(Void);

Description

When buffer memory is allocated, it will be released automatically by calling the SFXRingBuffer::Free function.

Reference

SFXRingBuffer::Free

SFXRingBuffer::Allocate

Allocate buffer memory.

[ public ]
SFCError Allocate(
    UInt32 size   // memory size to allocate
);

Return value

Success : SFERR_NO_ERROR
If insufficient memory : SFERR_NO_MEMOERY

Description

Since buffer memory is not allocated in the constructor, it is necessary to allocate buffer memory by using the SFXRingBuffer::Allocate function.

The behaviour is not defined when calling other functions without allocation.

Example

SFXRingBuffer ring;

// allocate 256 byte of memory
if (ring.Allocate(256) == SFERR_NO_ERROR) {
    ...
}

Reference

SFXRingBuffer::SFXRingBuffer | SFXRingBuffer::Free

SFXRingBuffer::EmptyInstance

Get an empty ring buffer.

[ public, static ]
SFXRingBufferConstRef EmptyInstance(Void);

Description

Get an instance that represents an empty ring buffer.

SFXRingBuffer::FirstIndexOf

Get the first index of SFXRingBuffer object to match with the specified data, searching from the beginning.

[ public, const ]
SInt32 FirstIndexOf(
    SFXBufferConstRef buffer        // buffer object to match with
    SInt32 index = SINT32_MINIMUM   // starting index to search from
);

[ public, const ]
SInt32 FirstIndexOf(
    VoidConstPtr buffer             // buffer data to match with
    UInt32 size                     // size of buffer data to match with
    SInt32 index = SINT32_MINIMUM   // starting index to search from
);

[ public, const ]
SInt32 FirstIndexOf(
    Byte byte                       // byte data to match with
    SInt32 index = SINT32_MINIMUM   // starting index to search from
);

Return value

Success : The first index where found.
If failed : -1

Description

The index value of read pointer is regarded as "0".

To search from other than the beginning, specify the starting index to match with. (The origin index is 0.)

Example

static ByteConst data[] = {
        '1', '2', '3', '4', '5', '6', '7', '8'
    };
SFXRingBuffer ring;
SFXBuffer buffer;

// set the size of ring buffer to 256 bytes
if (ring.Allocate(256) == SFERR_NO_ERROR) {

    // write 8 byte of data
    if (ring.Write(data, sizeof(data)) == SFERR_NO_ERROR) {
        
        // get the first index of SFXRingBuffer object to match with the specified data, searching from the beginning
        TRACE("FirstIndexOf('2') = %d", ring.FirstIndexOf('2'));  // FirstIndexOf('2') = 1
        TRACE("FirstIndexOf('9') = %d", ring.FirstIndexOf('9'));  // FirstIndexOf('9') = -1
    }
}

Reference

SFXRingBuffer::LastIndexOf

SFXRingBuffer::Free

Release the buffer memory that the SFXRingBuffer object manages.

[ public ]
Void Free(Void);

Description

Release the buffer memory allocated by using the SFXRingBuffer::Allocate function.

If the SFXRingBuffer object has no buffer memory, nothing happens.

Example

SFXRingBuffer ring;

// allocate 256 byte of memory
if (ring.Allocate(256) == SFERR_NO_ERROR) {
    ...
    
    ring.Free();  // release memory explicitly
}

Reference

SFXRingBuffer::Allocate

SFXRingBuffer::GetReadableBuffer

Get the read pointer.

[ public, const ]
VoidConstPtr GetReadableBuffer(
    UInt32Ptr size   // size of data area that can be read through the read pointer
);

Description

Get the read pointer to the buffer memory allocated internally. By using this pointer, data can be read directly from the internal buffer.

The "size" parameter will be set to the size of data area that can be read through the read pointer. This size does not always equal the return value of SFXRingBuffer::GetReadableSize function, and usually it will be less than that value.

To read the size of data returned by the SFXRingBuffer::GetReadableSize function, it is necessary to call both SFXRingBuffer::GetReadableBuffer and SFXRingBuffer::SeekRead function several times.

Example

Write all the data to be read from the ring buffer onto the output stream.

Void WriteRingBufferToFile(SFXBinaryStreamWriterRef stream, SFXRingBufferRef ring)
{
    UInt32 totalSize;   // total size of data that can be read from the ring buffer

    totalSize = ring.GetReadableSize();
    while (totalSize > 0) {
        UInt32 readableSize;
        VoidPtr readPtr;     // read pointer
 
        readPtr = ring.GetReadableBuffer(&readableSize);
        stream.Write(readPtr, readableSize);
        ring.SeekRead(readPtr, readableSize);

        totalSize -= readableSize;
    }
}

Reference

SFXRingBuffer::GetReadableBuffer | SFXRingBuffer::GetReadableSize | SFXRingBuffer::SeekRead

SFXRingBuffer::GetReadableSize

Get the size of data area that can be read through the read pointer.

[ public, const ]
UInt32 GetReadableSize(Void);

Example

static ByteConst data[] = {
        '1', '2', '3', '4', '5', '6', '7', '8'
};
SFXRingBuffer ring;
SFXBuffer buffer;

// set the size of ring buffer to 256 bytes
if (ring.Allocate(256) == SFERR_NO_ERROR) {

    TRACE("GetSize = %d", ring.GetSize());                  // GetSize = 256
    TRACE("GetWritableSize = %d", ring.GetWritableSize());  // GetWritableSize = 256
    TRACE("GetReadableSize = %d", ring.GetReadableSize());  // GetReadableSize = 0
		

    // write 8 byte of data
    if (ring.Write(data, sizeof(data)) == SFERR_NO_ERROR) {

        TRACE("GetSize = %d", ring.GetSize());                   // GetSize = 256
        TRACE("GetWritableSize = %d", ring.GetWritableSize());   // GetWritableSize = 248
        TRACE("GetReadableSize = %d", ring.GetReadableSize());   // GetReadableSize = 8

        // allocate buffer for reading
        buffer.SetSize(4);

        // read 4 byte of data
        if (ring.Read(&buffer) == SFERR_NO_ERROR) {

            TRACE("GetSize = %d", ring.GetSize());                   // GetSize = 256
            TRACE("GetWritableSize = %d", ring.GetWritableSize());   // GetWritableSize = 252
            TRACE("GetReadableSize = %d", ring.GetReadableSize());   // GetReadableSize = 4

        }
    }
}

Reference

SFXRingBuffer::GetReadableBuffer | SFXRingBuffer::GetWritableSize

SFXRingBuffer::GetSize

Get the size of buffer memory.

[ public, const ]
UInt32 GetSize(Void);

Description

From the property of ring buffer, the following equation is always valid.

SFXRingBuffer::GetSize = SFXRingBuffer::GetReadableSize + SFXRingBuffer::GetWritableSize

Example

static ByteConst data[] = {
        '1', '2', '3', '4', '5', '6', '7', '8'
};
SFXRingBuffer ring;
SFXBuffer buffer;

// set the size of ring buffer to 256 bytes
if (ring.Allocate(256) == SFERR_NO_ERROR) {

    TRACE("GetSize = %d", ring.GetSize());                  // GetSize = 256
    TRACE("GetWritableSize = %d", ring.GetWritableSize());  // GetWritableSize = 256
    TRACE("GetReadableSize = %d", ring.GetReadableSize());  // GetReadableSize = 0
		

    // write 8 byte of data
    if (ring.Write(data, sizeof(data)) == SFERR_NO_ERROR) {

        TRACE("GetSize = %d", ring.GetSize());                   // GetSize = 256
        TRACE("GetWritableSize = %d", ring.GetWritableSize());   // GetWritableSize = 248
        TRACE("GetReadableSize = %d", ring.GetReadableSize());   // GetReadableSize = 8

        // allocate buffer for reading
        buffer.SetSize(4);

        // read 4 byte of data
        if (ring.Read(&buffer) == SFERR_NO_ERROR) {

            TRACE("GetSize = %d", ring.GetSize());                   // GetSize = 256
            TRACE("GetWritableSize = %d", ring.GetWritableSize());   // GetWritableSize = 252
            TRACE("GetReadableSize = %d", ring.GetReadableSize());   // GetReadableSize = 4

        }
    }
}

Reference

SFXRingBuffer::GetReadableSize | SFXRingBuffer::GetWritableSize

SFXRingBuffer::GetWritableBuffer

Get the write pointer.

[ public ]
VoidPtr GetWritableBuffer(
    UInt32Ptr size   // size of data area that can be written through the write pointer
);

Description

Get the write pointer to the buffer memory allocated internally. By using this pointer, data can be written directly onto the internal buffer.

The "size" parameter will be set to the size of data area that can be written through the write pointer. This size does not always equal the return value of SFXRingBuffer::GetWritableSize function, and usually it will be less than that value.

To write the size of data returned by the SFXRingBuffer::GetWritableSize function, it is necessary to call both SFXRingBuffer::GetWritableBuffer and SFXRingBuffer::SeekWrite function several times.

Example

Read from the input stream, and write all the data onto the ring buffer.

Void WriteRingBufferFromFile(SFXBinaryStreamReaderRef stream, SFXRingBufferRef ring)
{
    UInt32 totalSize;  // total size of data that can be written onto the ring buffer
    UInt32 availSize;  // total size of data that can be read from the file

    totalSize = ring.GetWritableSize();
    availSize = stream.GetReadableSize();

    while (totalSize > 0 && availSize > 0) {
        UInt32 writableSize;
        VoidPtr writePtr;
        UInt32 writtenSize;  // data size to write actually
 
        writePtr = ring.GetWritableBuffer(&writableSize);
        {
            writtenSize = (availSize < writableSize) ? availSize : writableSize;
            stream.Read(writePtr, writtenSize);
        }
        ring.SeekRead(readPtr, readableSize);

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

Reference

SFXRingBuffer::GetWritableBuffer | SFXRingBuffer::GetWritableSize | SFXRingBuffer::SeekWrite

SFXRingBuffer::GetWritableSize

Get the size of data area that can be written through the write pointer.

[ public, const ]
UInt32 GetWritableSize(Void);

Example

static ByteConst data[] = {
        '1', '2', '3', '4', '5', '6', '7', '8'
};
SFXRingBuffer ring;
SFXBuffer buffer;

// set the size of ring buffer to 256 bytes
if (ring.Allocate(256) == SFERR_NO_ERROR) {

    TRACE("GetSize = %d", ring.GetSize());                  // GetSize = 256
    TRACE("GetWritableSize = %d", ring.GetWritableSize());  // GetWritableSize = 256
    TRACE("GetReadableSize = %d", ring.GetReadableSize());  // GetReadableSize = 0
		

    // write 8 byte of data
    if (ring.Write(data, sizeof(data)) == SFERR_NO_ERROR) {

        TRACE("GetSize = %d", ring.GetSize());                   // GetSize = 256
        TRACE("GetWritableSize = %d", ring.GetWritableSize());   // GetWritableSize = 248
        TRACE("GetReadableSize = %d", ring.GetReadableSize());   // GetReadableSize = 8

        // allocate buffer for reading
        buffer.SetSize(4);

        // read 4 byte of data
        if (ring.Read(&buffer) == SFERR_NO_ERROR) {

            TRACE("GetSize = %d", ring.GetSize());                   // GetSize = 256
            TRACE("GetWritableSize = %d", ring.GetWritableSize());   // GetWritableSize = 252
            TRACE("GetReadableSize = %d", ring.GetReadableSize());   // GetReadableSize = 4

        }
    }
}

Reference

SFXRingBuffer::GetWritableBuffer | SFXRingBuffer::GetReadableSize

SFXRingBuffer::LastIndexOf

Get the last index of SFXRingBuffer object to match with the specified data, searching from the end.

[ public, const ]
SInt32 LastIndexOf(
    SFXBufferConstRef buffer        // buffer object to match with
    SInt32 index = SINT32_MAXIMUM   // starting index to search from
);

[ public, const ]
SInt32 LastIndexOf(
    VoidConstPtr buffer             // buffer data to match with
    UInt32 buffer                   // size of buffer data to match with
    SInt32 index = SINT32_MAXIMUM   // starting index to search from
);

[ public, const ]
SInt32 LastIndexOf(
    Byte byte                       // byte data to match with
    SInt32 index = SINT32_MAXIMUM   // starting index to search from
);

Return value

Success : The last index where found.
If failed : -1

Description

The index value of read pointer is regarded as "0".

To search from other than the end, specify the starting index to match with. (The origin index is 0.)

Example

static ByteConst data[] = {
        '1', '2', '3', '4', '5', '6', '7', '8'
    };
SFXRingBuffer ring;
SFXBuffer buffer;

// set the size of ring buffer to 256 bytes
if (ring.Allocate(256) == SFERR_NO_ERROR) {

    // write 8 byte of data
    if (ring.Write(data, sizeof(data)) == SFERR_NO_ERROR) {
        
        // get the last index of SFXRingBuffer object to match with the specified data, searching from the end
        TRACE("LastIndexOf('2') = %d", ring.LastIndexOf('2'));  // LastIndexOf('2') = 1
        TRACE("LastIndexOf('9') = %d", ring.LastIndexOf('9'));  // LastIndexOf('9') = -1
    }
}

Reference

SFXRingBuffer::FirstIndexOf

SFXRingBuffer::Read

Read data.

[ public ]
SFCError Read(
    VoidPtr buffer   // buffer for reading data
    UInt32 size      // data size to read
);

[ public ]
SFCError Read(
    SFXBufferPtr buffer   // buffer for reading data
);

Return value

Success : SFERR_NO_ERROR
If argument is invalid : SFERR_INVALID_PARAM
If "size" argument exceeds the return value of SFXRingBuffer::GetReadableSize function : SFERR_FAILED

Example

 static ByteConst data[] = {
        '1', '2', '3', '4', '5', '6', '7', '8'
    };
SFXRingBuffer ring;
SFXBuffer buffer;

// set the size of ring buffer to 256 bytes
if (ring.Allocate(256) == SFERR_NO_ERROR) {

    // write 8 byte of data
    if (ring.Write(data, sizeof(data)) == SFERR_NO_ERROR) {

        // allocate buffer for reading
        buffer.SetSize(4);

        // read 4 byte of data
        if (ring.Read(&buffer) == SFERR_NO_ERROR) {

            // display the content of ring buffer
            TRACE("%c, %c, %c, %c", buffer[0], buffer[1], buffer[2], buffer[3]); // 1, 2, 3, 4
                
        }
    }
}

Reference

SFXRingBuffer::Write

SFXRingBuffer::Reset

Clear the written data.

[ public ]
Void Reset(Void);

Description

Just after calling the SFXRingBuffer::Reset function, the size of area to be read will be "0" and the size of area to be written will equal that of ring buffer.

Reference

SFXRingBuffer::GetReadableSize | SFXRingBuffer::GetWritableSize

SFXRingBuffer::SeekRead

Set forward the read pointer.

[ public ]
SFCError SeekRead(
    UInt32 size   // size to set forward the read pointer
);

Return value

Success : SFERR_NO_ERROR
If "size" parameter exceeds the return value of SFXRingBuffer::GetReadableSize function : SFERR_FAILED

Description

The SFXRingBuffer::SeekRead sets forward the read pointer by the value of "size" parameter.

Example

 static ByteConst data[] = {
        '1', '2', '3', '4', '5', '6', '7', '8'
    };
SFXRingBuffer ring;
SFXBuffer buffer;

// set the size of ring buffer to 256 bytes
if (ring.Allocate(256) == SFERR_NO_ERROR) {

    // write 8 byte of data
    if (ring.Write(data, sizeof(data)) == SFERR_NO_ERROR) {

        // allocate buffer for reading
        buffer.SetSize(4);

        // set forward the read pointer
        ring.SeekRead(2);

        // read 4 byte of data
        if (ring.Read(&buffer) == SFERR_NO_ERROR) {

            // display the content of ring buffer
            TRACE("%c, %c, %c, %c", buffer[0], buffer[1], buffer[2], buffer[3]); // 3, 4, 5, 6
                
        }
    }
}

Reference

SFXRingBuffer::GetReadableBuffer | SFXRingBuffer::GetReadableSize

SFXRingBuffer::SeekWrite

Set forward the write pointer.

[ public ]
SFCError SeekWrite(
    UInt32 size   // size to set forward the write pointer
);

Return value

Success : SFERR_NO_ERROR
If "size" parameter exceeds the return value of SFXRingBuffer::GetWritableSize function : SFERR_FAILED

Description

The SFXRingBuffer::SeekWrite sets forward the write pointer by the value of "size" parameter.

Example

 static ByteConst data[] = {
        '1', '2', '3', '4', '5', '6', '7', '8'
    };
SFXRingBuffer ring;
SFXBuffer buffer;

// set the size of ring buffer to 256 bytes
if (ring.Allocate(256) == SFERR_NO_ERROR) {

    // set forward the write pointer
    ring.SeekWrite(2);

    // write 8 byte of data
    if (ring.Write(data, sizeof(data)) == SFERR_NO_ERROR) {

        // allocate buffer for reading
        buffer.SetSize(4);

        // read 4 byte of data
        if (ring.Read(&buffer) == SFERR_NO_ERROR) {

            // display the content of ring buffer
            TRACE("%c, %c, %c, %c", buffer[0], buffer[1], buffer[2], buffer[3]); // , , 1, 2
                
        }
    }
}

Reference

SFXRingBuffer::GetWritableBuffer | SFXRingBuffer::GetWritableSize

SFXRingBuffer::Write

Write data.

[ public ]
SFCError Write(
    VoidConstPtr buffer   // buffer for writing data
    UInt32 size           // data size to write
);

[ public ]
SFCError Write(
    SFXBufferConstRef buffer   // buffer for writing data
);

Return value

Success : SFERR_NO_ERROR
If argument is invalid : SFERR_INVALID_PARAM
If "size" argument exceeds the return value of SFXRingBuffer::GetWritableSize function : SFERR_FAILED

Example

 static ByteConst data[] = {
        '1', '2', '3', '4', '5', '6', '7', '8'
    };
SFXRingBuffer ring;
SFXBuffer buffer;

// set the size of ring buffer to 256 bytes
if (ring.Allocate(256) == SFERR_NO_ERROR) {

    // write 8 byte of data
    if (ring.Write(data, sizeof(data)) == SFERR_NO_ERROR) {

        // allocate buffer for reading
        buffer.SetSize(4);

        // read 4 byte of data
        if (ring.Read(&buffer) == SFERR_NO_ERROR) {

            // display the content of ring buffer
            TRACE("%c, %c, %c, %c", buffer[0], buffer[1], buffer[2], buffer[3]); // 1, 2, 3, 4
                
        }
    }
}

Reference

SFXRingBuffer::Read