BlitzMax Extended  0.8.18
Pushing Blitz to the Max.
Functions
blitz_memory.h File Reference

Basic memory handling functions. More...

#include "_common.h"

Go to the source code of this file.

Functions

void * bbMemAlloc (BBInt size) __attribute__((malloc))
 Allocates a continous block of aligned memory.
void bbMemFree (void *mem)
 Frees a previously allocated block of aligned memory.
void * bbMemExtend (void *mem, BBInt size, BBInt new_size)
 Changes the size of a block of memory.
void bbMemClear (void *dst, BBInt size)
 Clears a block of memory to 0.
void bbMemCopy (void *dst, const void *src, BBInt size)
 Copies the content of a block of memory into another.
void bbMemMove (void *dst, const void *src, BBInt size)
 Moves the data from one memory location to another.

Detailed Description

Basic memory handling functions.

The garbage collector needs memory to aligned on a 16-bit boundary. So if you have to interact with it, use the following wrapper functions.

Author:
Mark Sibly
Fabian Niemann

Function Documentation

void* bbMemAlloc ( BBInt  size)

Allocates a continous block of aligned memory.

Both versions of BlitzMax's GC need the memory to be aligned on a 16-byte boundary in order to work correctly. This function provides such an alignment.

If the allocation failed, it tries to free unused memory by manually calling the GC's collect function. Only if this also fails, NULL is returned.

Parameters:
sizeThe size of memory in bytes
Returns:
A pointer to the newly allocated memory, or NULL.

Referenced by bbIncbinAdd(), bbMemExtend(), bbStringToCString(), bbStringToUTF8String(), and bbStringToWString().

void bbMemClear ( void *  dst,
BBInt  size 
)

Clears a block of memory to 0.

When allocated, a block of memory is not filled with anything one could expect. Therefore it is always a good idea to clear the block before using it or ensuring that it is filled completely with the right data.

Parameters:
dstThe memory block which is to be cleared
sizeThe size of the memory block in bytes
void bbMemCopy ( void *  dst,
const void *  src,
BBInt  size 
)

Copies the content of a block of memory into another.

Warning:
The two blocks (destination and source) may NOT overlap in memory, otherwise the behaviour is undefined.
Parameters:
dstThe memory block to which the data is copied
srcThe memory block containing the data
sizeThe exact number of bytes that are copied
void* bbMemExtend ( void *  mem,
BBInt  size,
BBInt  new_size 
)

Changes the size of a block of memory.

The name of this function can be misleading, as it actually allocates a new block of memory with the given new_size and copies into it the contents of the old one.

If new_size is larger than size, than the data from mem is copied completely and everything after its original size contains undefined values (all the stuff that has been there before).

If on the other hand new_size is smaller than size, only the beginning of the data from mem is copied there. You will lose the rest.

The original memory block pointed to by mem is freed after copying.

See also:
bbMemAlloc
Parameters:
memA pointer to the block of memory to be copied
sizeThe size of the memory block in bytes
new_sizeThe size of the newly allocated memory block
Returns:
A pointer to the newly allocated block of memory, or NULL on failure.
void bbMemFree ( void *  mem)

Frees a previously allocated block of aligned memory.

Before attempting to free the given block of memory, a check for a non-null pointer is performed.

Parameters:
memA pointer to the block of memory to be freed.
void bbMemMove ( void *  dst,
const void *  src,
BBInt  size 
)

Moves the data from one memory location to another.

Note:
The two blocks (destination and source) can overlap.
Parameters:
dstThe memory location to which the data is moved
srcThe memory block containing the data
sizeThe exact number of bytes that are moved