Memory Management


Defines

#define FREE_MEMORY   3
#define LEAVE_MEMORY   2

Functions

void* malloc (size_t size)
void* calloc (size_t number, size_t size)
void* realloc (void *ptr_memory_block, size_t new_size)
void free (void *ptr_memory_block)
bool is_low_memory (void)
size_t get_safety_pool_size (void)
void* memset (void *ptr_buffer, int value, size_t size)
void* memcpy (void *ptr_buffer, void *ptr_source, size_t size)
void* memmove (void *dst, void *src, size_t size)
int memcmp (void *ptr_buff_1, void *ptr_buff_2, size_t size)
void memory_dump (void *ptr_memory, int size, int string_length)

Detailed Description

CyOS routines you can use to allocate, manipulate and free memory.

Define Documentation

#define FREE_MEMORY   3
 

Frees the memory block allocated for the object (used in destructor).

#define LEAVE_MEMORY   2
 

Doesn't free the memory block allocated for the object (used in destructor).

Function Documentation

void * calloc ( size_t number,
size_t size )
 

Allocates an array in memory, with elements initialized to 0.
You can only free this memory block - by calling free().

Parameters:
number   the number of elements to allocate
size   the length in bytes of each element.
Returns:
a void pointer to the allocated space, or NULL if there is insufficient memory available 
       #include <cybiko.h>
       #define  MAX_OBJECTS     100
       ...
       struct cObject* ptr_object_array;
       ...
       ptr_object_array = (struct cObject*)calloc( MAX_OBJECTS,
                                                   sizeof(struct cObject) );
       ...
       free(ptr_object_array);
       ...
See also:
free.

void free ( void * ptr_memory_block )
 

Frees a memory block.

Parameters:
ptr_memory_block   a pointer to previously allocated memory block
Returns:
None 
       #include <cybiko.h>
       #define  MAX_STR_LEN     256
       ...
       char* sz_string;
       ...
       sz_string = (char*)malloc( MAX_STR_LEN );
       ...
       free(sz_string);
       ...
See also:
malloc, calloc, realloc.

size_t get_safety_pool_size ( void )
 

Returns safety pool size.

Returns:
maximum size of the memory pool that can be allocated. 
       #include <cybiko.h>
       ...
       if ( get_safety_pool_size() < 1024 )
       {
         TRACE( "Error! Not enough memory." );
         return -1;
       }
       ...

bool is_low_memory ( void )
 

Returns low memory alarm.
The system sets it automatically when the dynamic memory pool drops dangerously low. All applications should check dynamic memory. When TRUE is returned, the application should free up all possible dynamically allocated memory. When it is set to TRUE.

Returns:
TRUE if memory is low 
       #include <cybiko.h>
       ...
       if( is_low_memory() )
       {
         TRACE( "Warning! Low memory." );
       }
       ...

void * malloc ( size_t size )
 

Allocates memory blocks.
Afterward you must free this memory block by calling free().

Parameters:
size   number of bytes to allocate
Returns:
a void pointer to the allocated space, or NULL if there is insufficient memory available 
       #include <cybiko.h>
       #define  MAX_STR_LEN     256
       ...
       char* sz_string;
       ...
       sz_string = (char*)malloc( MAX_STR_LEN );
       ...
       free(sz_string);
       ...
See also:
free.

int memcmp ( void * ptr_buff_1,
void * ptr_buff_2,
size_t size )
 

Compares characters in two buffers.

Parameters:
ptr_buff_1   a pointer to first buffer.
ptr_buff_2   a pointer to second buffer.
size   number of characters to compare.
Returns:
0 if ptr_buff_1 identical to ptr_buff_2. Positive value if ptr_buff_1 is greater(in lexical meaning) than ptr_buff_2. Negative value if ptr_buff_1 is less(in lexical meaning) than ptr_buff_2. 
       char* string_1 = "AAAAAAAAAB";
       char* string_2 = "AAAAAAAAAA";
       ...
       if( !memcmp( string_1, string_2, 10 ) )
       {
         //  Buffers are not identical, because
         //  string_1 is greater then string_2 in lexical meaning.
         ...
       }
       ...

void * memcpy ( void * ptr_buffer,
void * ptr_source,
size_t size )
 

Copies characters between buffers.
If the source and destination overlap, this function does not ensure that the original source bytes in the overlapping region are copied before being overwritten. Use memmove() to handle overlapping regions.

Parameters:
ptr_buffer   a pointer to destination.
ptr_source   a pointer to source.
size   number of characters to copy.
Returns:
a pointer to destination. 
       #include <cybiko.h>
       ...
       const char* sz_base_string = "Hello,";
       const char* sz_name = "word";
       char* sz_string[20];
       ...
       memcpy( sz_string,
               sz_base_string,
               strlen( sz_base_string ) );
       memcpy( sz_string + strlen( sz_string ),
               sz_name,
               strlen( sz_name ) );
       memcpy( sz_string + strlen( sz_string ),
               "!",
               2 );
       //  Traces Hello, world!
       TRACE( "Result: %s", sz_string );
       ...
See also:
memmove.

void * memmove ( void * dst,
void * src,
size_t size )
 

Moves one buffer to another.
If some regions of the source area and the destination overlap, memmove() ensures that the original source bytes in the overlapping region are copied before being overwritten.

Parameters:
ptr_buffer   a pointer to destination.
ptr_source   a pointer to source.
size   number of characters to copy.
Returns:
a pointer to destination. 
       #include <cybiko.h>
       ...
       const char* sz_string = "The funny black cat.";
       ...
       memmove( sz_string + 4, sz_string + 10, 6 );
       //  Traces "The black black cat."
       TRACE( "Result: %s", sz_string );
See also:
memcpy.

void memory_dump ( void * ptr_memory,
int size,
int string_length )
 

Trace memory dump.

Parameters:
ptr_memory   pointer to the memory dump
size   the size of the memory dump
string_length   the maximum length of a string on the console
Returns:
None 
        #include <cywin.h>
        ...
        char* raw_data = (char*)malloc( 0x100 );
        ...
        //  Fills raw_data array.
        ...
        memory_dump( raw_data, 256, 16 );
        ...
        free( raw_data );
        ...

void * memset ( void * ptr_buffer,
int value,
size_t size )
 

Sets buffers to a specified character.

Parameters:
ptr_buffer   a pointer to destination.
value   a character to set.
size   number of characters.
Returns:
a pointer to destination. 
       #include <cybiko.h>
       #define MAX_PLAYER      10
       ...
       struct Point
       {
         int x;
         int y;
       } players_coordinates[MAX_PLAYER];
       ...
       //  Initializes players' coordinates.
       memset( players_coordinates, 0, MAX_PLAYER*sizeof(struct Point) );
       ...

void * realloc ( void * ptr_memory_block,
size_t new_size )
 

Reallocates memory blocks.
Afterward you must free this memory block by calling free().

Parameters:
ptr_memory_block   pointer to a previously allocated memory block
new_size   new size in bytes
Returns:
a pointer to the reallocated memory block 
       #include <cybiko.h>
       ...
       char* sz_string;
       char* sz_source_string;
       ...
       sz_string = (char*)malloc( 10 );
       ...
       if( strlen( sz_source_string ) <= 10)
       {
         sz_string = (char*)realloc( sz_string,
                                     strlen( sz_source_string ) + 1 );
       }
       ...
       free(sz_string);
       ...
See also:
free.