Cosm API - Memory Buffer Functions

[Cosm Logo]

Memory Buffer Functions

v3BufferCreate
v3BufferLength
v3BufferClear
v3BufferPut
v3BufferGet
v3BufferUnget
v3BufferFree

v3BufferCreate

Syntax

#include "buffer.h"
s32 v3BufferCreate( v3_BUFFER * buffer, u64 size, u32 mode,
  u64 grow, const void * data, u64 length );

Description

Create a new buffer in buffer, initially assigning size bytes to its memory buffer. Once the buffer fills up it will allocate more memory in chunks of grow bytes. If grow is zero the buffer will never grow and may become full. If data is not NULL then length bytes will be copied from data and into the new buffer. mode determines which kind of buffer should be created. If you intend to access a buffer from more then one thread, be sure to wrap any calls in a mutex.

Modes

V3_BUFFER_MODE_QUEUE: Creates the buffer as a queue. A queue is a FIFO (first in, first out), this means that the first item to be added to the buffer will also be first item retrieved from the buffer.
V3_BUFFER_MODE_STACK: Creates the buffer as a stack. A stack is a LIFO (last in, first out), this means that the last item to be added to the buffer will be the first item retrieved from the buffer. The analogy for this is a stack of trays where you always take a new tray from the top.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_BUFFER_ERROR_MEMORY: Not enough memory left.
V3_BUFFER_ERROR_MODE: Unknown mode.
V3_BUFFER_ERROR_FULL: Buffer already created or not zeroed.

Example

  v3_BUFFER * buf;
  u64 size, grow;

  if ( ( buf = v3MemAlloc( v3u64u32( sizeof( v3_BUFFER ) ),
    V3_MEM_NORMAL ) ) == NULL )
  {
    /* Error in memory allocation. */
    return( V3_FAIL );
  }

  _V3_SET64( size, 00000000, 00000400 );
  _V3_SET64( grow, 00000000, 00000200 );

  if ( v3BufferCreate( buf, size, V3_BUFFER_MODE_QUEUE, grow, NULL,
    v3u64u32( 0 ) ) == V3_FAIL )
  {
    /* Failed */
    return( V3_FAIL );
  }

v3BufferLength

Syntax

#include "buffer.h"
u64 v3BufferLength( v3_BUFFER * buffer );

Description

Gives the length of the data currently in buffer.

Return Values

The length of the data currently in buffer.

Errors

None.

Example

  v3_BUFFER * buf;
  u64 size, grow;
  u64 length;

  if ( ( buf = v3MemAlloc( v3u64u32( sizeof( v3_BUFFER ) ),
    V3_MEM_NORMAL ) ) == NULL )
  {
    /* Error in memory allocation. */
    return( V3_FAIL );
  }

  _V3_SET64( size, 00000000, 00000400 );
  _V3_SET64( grow, 00000000, 00000200 );

  if ( v3BufferCreate( buf, size, V3_BUFFER_MODE_QUEUE, grow, NULL,
    v3u64u32( 0 ) ) == V3_FAIL )
  {
    /* Failed */
    return( V3_FAIL );
  }

  length = v3BufferLength( buf ); /* Should be zero. */

v3BufferClear

Syntax

#include "buffer.h"
s32 v3BufferClear( v3_BUFFER * buffer );

Description

Sets the length of the buffer to 0 without freeing it.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_BUFFER_ERROR_MEMORY: Invalid buffer parameter.

Example

  v3_BUFFER * buf;
  u64 length;

  /* ... */

  v3BufferClear( buf );
  length = v3BufferLength( buf ); /* Should be zero. */

v3BufferPut

Syntax

#include "buffer.h"
s32 v3BufferPut( v3_BUFFER * buffer, const void * data, u64 length );

Description

Inserts length bytes of data into buffer.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_BUFFER_ERROR_MEMORY: Not enough memory left.
V3_BUFFER_ERROR_FULL: The buffer is full, this will only happen if grow was 0 in v3BufferCreate.

Example

  v3_BUFFER * buf;
  u64 size, grow;
  u32 data, counter, data;

  if ( ( buf = v3MemAlloc( v3u64u32( sizeof( v3_BUFFER ) ),
    V3_MEM_NORMAL ) ) == NULL )
  {
    /* Error in memory allocation. */
    return( V3_FAIL );
  }

  _V3_SET64( size, 00000000, 00000400 );
  _V3_SET64( grow, 00000000, 00000200 );

  if ( v3BufferCreate( buf, size, V3_BUFFER_MODE_QUEUE, grow, NULL,
    v3u64u32( 0 ) ) == V3_FAIL )
  {
    /* Failed */
    return( V3_FAIL );
  }

  /* Lets insert some u32's into the buffer.
     They are 4 bytes each. */
  for ( counter = 0; counter < 20; counter++ )
  {
    data = counter * counter;
    if ( v3BufferPut( buf, &data, sizeof( u32 ) ) != V3_PASS )
    {
      /* Error. */
      return( V3_FAIL );
    }
  }

v3BufferGet

Syntax

#include "buffer.h"
u64 v3BufferGet( void * data, u64 length, v3_BUFFER * buffer );

Description

Gets as many bytes as possible, up to a maximum of length from buffer placing them into data. Note that while a stack will return your data-items in reverse order it will consider the size of a data-item to be length bytes and keep the internal byte-order.

Return Values

length on success, otherwise bytes read out of the buffer.

Errors

None.

Example

  v3_BUFFER * buf;
  u64 size, grow;
  u32 data, counter, data;

  if ( ( buf = v3MemAlloc( v3u64u32( sizeof( v3_BUFFER ) ),
    V3_MEM_NORMAL ) ) == NULL )
  {
    /* Error in memory allocation. */
    return( V3_FAIL );
  }

  _V3_SET64( size, 00000000, 00000400 );
  _V3_SET64( grow, 00000000, 00000200 );

  if ( v3BufferCreate( buf, size, V3_BUFFER_MODE_STACK, grow, NULL,
    v3u64u32( 0 ) ) == V3_FAIL )
  {
    /* Failed */
    return( V3_FAIL );
  }

  /* Lets insert some u32's into the buffer.
     They are four bytes each. */
  for ( counter = 0; counter < 20; counter++ )
  {
    data = counter * counter;
    if ( v3BufferPut( buf, &data, sizeof(u32) ) != V3_PASS )
    {
      /* Error. */
      return( V3_FAIL );
    }
  }

  /*
    Lets retrieve the data. We should be getting the squares
     of the numbers from 0 to 19 in reverse order.
  */
  for ( counter = 0; counter < 20; counter ++ )
  {
    if ( v3BufferGet( &data, sizeof( u32 ), buf ) != sizeof( u32 ) )
    {
      /* An error.*/
      return( V3_FAIL );
    }
    /* do something with data. */
  }

v3BufferUnget

Syntax

#include "buffer.h"
s32 v3BufferUnget( v3_BUFFER * buffer, const void * data, u64 length );

Description

Inserts length bytes of data into buffer. The difference from v3BufferPut is that the data is placed so it will be the first data retrieved by a v3BufferGet. Note: be careful when using this function in a multithreaded environment.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_BUFFER_ERROR_MEMORY: Not enough memory left.
V3_BUFFER_ERROR_FULL: The buffer is full, this will only happen if grow was 0 in v3BufferCreate.
V3_BUFFER_ERROR_MODE: Unknown mode.

Example

  v3_BUFFER * buf;
  u64 size, grow;
  u32 data, counter, data;

  if ( ( buf = v3MemAlloc( v3u64u32( sizeof( v3_BUFFER ) ),
    V3_MEM_NORMAL ) ) == NULL )
  {
    /* Error in memory allocation. */
    return( V3_FAIL );
  }

  _V3_SET64( size, 00000000, 00000400 );
  _V3_SET64( grow, 00000000, 00000200 );

  if ( v3BufferCreate( buf, size, V3_BUFFER_MODE_STACK, grow, NULL,
    v3u64u32( 0 ) ) == V3_FAIL )
  {
    /* Failed */
    return( V3_FAIL );
  }

  /* Lets insert some u32's into the buffer.
     They are four bytes each. */
  for ( counter = 0; counter < 20; counter++ )
  {
    data = counter * counter;
    if ( v3BufferPut( buf, &data, sizeof( u32 ) ) != V3_PASS )
    {
      /* Error. */
      return( V3_FAIL );
    }
  }

  /* Lets retrieve the data. */
  for ( counter = 0; counter < 20; counter ++ )
  {
    if ( v3BufferGet( &data, sizeof( u32 ), buf ) != sizeof( u32 ) )
    {
      /* An error.*/
      return( V3_FAIL );
    }
    /*
      We keep pushing the data back on the stack, this means we will
      be getting the same data each time
    */
    if ( v3BufferUnget( buf, &data, sizeof( u32 ) ) != V3_PASS )
    {
      /* An error. */
      return( V3_FAIL );
    }
  }

v3BufferFree

Syntax

#include "buffer.h"
void v3BufferFree( v3_BUFFER * buffer);

Description

Free all data in the buffer and return it to an uninitialized state.

Return Values

None.

Errors

None.

Example

  v3_BUFFER * buf;

  /* Use of the buffer...*/

  v3BufferFree( buf );