Cosm API - Memory Buffer Functions

[Cosm Logo]

Memory Buffer Functions

CosmBufferInit
CosmBufferLength
CosmBufferClear
CosmBufferPut
CosmBufferGet
CosmBufferUnget
CosmBufferFree

CosmBufferInit

Syntax

#include "cosm/buffer.h"
s32 CosmBufferInit( cosm_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

COSM_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.
COSM_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

COSM_PASS on success, or an error code on failure.

Errors

COSM_BUFFER_ERROR_MEMORY: Not enough memory left.
COSM_BUFFER_ERROR_MODE: Unknown mode.
COSM_BUFFER_ERROR_FULL: Buffer already created or not zeroed.

Example

  cosm_BUFFER * buf;
  u64 size, grow;

  if ( ( buf = CosmMemAlloc( sizeof( cosm_BUFFER ) ) ) == NULL )
  {
    /* Error in memory allocation. */
    return COSM_FAIL;
  }

  size = 0x0000000000000400LL;
  grow = 0x0000000000000200LL;

  if ( CosmBufferInit( buf, size, COSM_BUFFER_MODE_QUEUE, grow, NULL,
    0 ) == COSM_FAIL )
  {
    /* Failed */
    return COSM_FAIL;
  }

CosmBufferLength

Syntax

#include "cosm/buffer.h"
u64 CosmBufferLength( cosm_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

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

  if ( ( buf = CosmMemAlloc( sizeof( cosm_BUFFER ) ) ) == NULL )
  {
    /* Error in memory allocation. */
    return COSM_FAIL;
  }

  size = 0x0000000000000400LL;
  grow = 0x0000000000000200LL;

  if ( CosmBufferInit( buf, size, COSM_BUFFER_MODE_QUEUE, grow, NULL,
    0 ) == COSM_FAIL )
  {
    /* Failed */
    return COSM_FAIL;
  }

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

CosmBufferClear

Syntax

#include "cosm/buffer.h"
s32 CosmBufferClear( cosm_BUFFER * buffer );

Description

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

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_BUFFER_ERROR_MEMORY: Invalid buffer parameter.

Example

  cosm_BUFFER * buf;
  u64 length;

  /* ... */

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

CosmBufferPut

Syntax

#include "cosm/buffer.h"
s32 CosmBufferPut( cosm_BUFFER * buffer, const void * data, u64 length );

Description

Inserts length bytes of data into buffer.

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_BUFFER_ERROR_MEMORY: Not enough memory left.
COSM_BUFFER_ERROR_FULL: The buffer is full, this will only happen if grow was 0 in CosmBufferInit.

Example

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

  if ( ( buf = CosmMemAlloc( sizeof( cosm_BUFFER ) ) ) == NULL )
  {
    /* Error in memory allocation. */
    return COSM_FAIL;
  }

  size = 0x0000000000000400LL;
  grow = 0x0000000000000200LL;

  if ( CosmBufferInit( buf, size, COSM_BUFFER_MODE_QUEUE, grow, NULL,
    0 ) == COSM_FAIL )
  {
    /* Failed */
    return COSM_FAIL;
  }

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

CosmBufferGet

Syntax

#include "cosm/buffer.h"
u64 CosmBufferGet( void * data, u64 length, cosm_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

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

  if ( ( buf = CosmMemAlloc( sizeof( cosm_BUFFER ) ) ) == NULL )
  {
    /* Error in memory allocation. */
    return COSM_FAIL;
  }

  size = 0x0000000000000400LL;
  grow = 0x0000000000000200LL;

  if ( CosmBufferInit( buf, size, COSM_BUFFER_MODE_STACK, grow, NULL,
    0 ) == COSM_FAIL )
  {
    /* Failed */
    return COSM_FAIL;
  }

  /* Lets insert some u32's into the buffer.
     They are four bytes each. */
  for ( counter = 0; counter < 20; counter++ )
  {
    data = counter * counter;
    if ( CosmBufferPut( buf, &data, sizeof(u32) ) != COSM_PASS )
    {
      /* Error. */
      return COSM_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 ( CosmBufferGet( &data, sizeof( u32 ), buf ) != sizeof( u32 ) )
    {
      /* An error.*/
      return COSM_FAIL;
    }
    /* do something with data. */
  }

CosmBufferUnget

Syntax

#include "cosm/buffer.h"
s32 CosmBufferUnget( cosm_BUFFER * buffer, const void * data, u64 length );

Description

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

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_BUFFER_ERROR_MEMORY: Not enough memory left.
COSM_BUFFER_ERROR_FULL: The buffer is full, this will only happen if grow was 0 in CosmBufferInit.
COSM_BUFFER_ERROR_MODE: Unknown mode.

Example

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

  if ( ( buf = CosmMemAlloc( sizeof( cosm_BUFFER ) ) ) == NULL )
  {
    /* Error in memory allocation. */
    return COSM_FAIL;
  }

  size = 0x0000000000000400LL;
  grow = 0x0000000000000200LL;

  if ( CosmBufferInit( buf, size, COSM_BUFFER_MODE_STACK, grow, NULL,
    0 ) == COSM_FAIL )
  {
    /* Failed */
    return COSM_FAIL;
  }

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

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

CosmBufferFree

Syntax

#include "cosm/buffer.h"
void CosmBufferFree( cosm_BUFFER * buffer);

Description

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

Return Values

None.

Errors

None.

Example

  cosm_BUFFER * buf;

  /* Use of the buffer...*/

  CosmBufferFree( buf );