OSAPI Heap

Macros
#define	OSAPI_ALIGNMENT_DEFAULT   (-1)
	Certain methods allow a default alignment: this should be an alignment that follows the "malloc" alignment of the architecture (aligned sufficiently to store any C-structure efficiently).
#define	OSAPI_Heap_is_address_aligned(location, alignment)
	Check if a particular address is aligned to an alignment.
#define	OSAPI_Heap_align_size_up(size, alignment)
	Aligns a particular address to an alignment alignment.

Typedefs
typedef RTI_INT32	OSAPI_Alignment_T
	The OSAPIAlignment is the alignment in bytes; an address is aligned when it is a positive integer multiple of the alignment.

Functions
void *	OSAPI_Heap_allocate (RTI_SIZE_T count, RTI_SIZE_T size)
	Allocates zero-initialized memory from the heap.
OSPSLDllExport void *	OSAPI_Heap_realloc (void *ptr, RTI_SIZE_T size)
	Reallocate memory from the heap.
void	OSAPI_Heap_free (void *ptr)
	Frees memory allocated from the heap.
OSPSLDllExport void	OSAPI_Heap_allocate_buffer (char **buffer, RTI_SIZE_T size, OSAPI_Alignment_T alignment)
	Allocate a block of memory of the provided size from the heap.
OSPSLDllExport void	OSAPI_Heap_free_buffer (void *buffer)
	A static method to return a block (that was previously allocated with OSAPI_Heap_allocate_buffer) to the heap.

Detailed Description

Macro Definition Documentation

OSAPI_ALIGNMENT_DEFAULT

#define OSAPI_ALIGNMENT_DEFAULT   (-1)

Certain methods allow a default alignment: this should be an alignment that follows the "malloc" alignment of the architecture (aligned sufficiently to store any C-structure efficiently).

OSAPI_Heap_is_address_aligned

#define OSAPI_Heap_is_address_aligned	(		location,
			alignment )

Value:

  (((RTI_UINT32)((char*)(location) - (char*)OSAPI_CC_NullPtr) % (alignment)) == 0)

Check if a particular address is aligned to an alignment.

OSAPI_Heap_align_size_up

#define OSAPI_Heap_align_size_up	(		size,
			alignment )

Value:

        (((size) + ((alignment) - 1U)) & (~((alignment) - 1U)))

Aligns a particular address to an alignment alignment.

Typedef Documentation

OSAPI_Alignment_T

typedef RTI_INT32 OSAPI_Alignment_T

The OSAPIAlignment is the alignment in bytes; an address is aligned when it is a positive integer multiple of the alignment.

Function Documentation

OSAPI_Heap_allocate()

void * OSAPI_Heap_allocate	(	RTI_SIZE_T	count,
		RTI_SIZE_T	size )

Allocates zero-initialized memory from the heap.

The function allocates count elements of size size and sets the memory region to 0.

NOTE: This operation assumes the specified size to be > 0; this operation is never used directly but it is only accessed by using one of the other allocate operations of OSAPI_Heap (e.g. allocate_struct, allocate_array, allocate_string...); these operations are implemented as macros and accept a "type" argument which is always converted to a size > 0 using the sizeof operator.

Parameters

[in]	count	The number of elements to allocate.
[in]	size	The size of the element; size is assumed to be always greater than 0.

Returns

. A pointer to a contiguous memory area guaranteed to be large enough store count elements of size size.

See Also OSAPI_Heap_free

OSAPI_Heap_realloc()

OSPSLDllExport void * OSAPI_Heap_realloc	(	void *	ptr,
		RTI_SIZE_T	size )

Reallocate memory from the heap.

Parameters

[in]	ptr	Currently allocated buffer
[in]	size	The new desired size

Returns

. A pointer to a contiguous memory area guaranteed to be large enough store size bytes, NULL if the reallocation failed.

See Also OSAPI_Heap_free

OSAPI_Heap_free()

void OSAPI_Heap_free

(

void *

ptr

)

Frees memory allocated from the heap.

The function frees memory previously allocated with OSAPI_Heap_allocate back to the heap.

Parameters

[in]

ptr

Pointer to region previous allocated with OSAPI_Heap_allocate

See Also OSAPI_Heap_allocate

References RTI_UINT32.

OSAPI_Heap_allocate_buffer()

OSPSLDllExport void OSAPI_Heap_allocate_buffer	(	char **	buffer,
		RTI_SIZE_T	size,
		OSAPI_Alignment_T	alignment )

Allocate a block of memory of the provided size from the heap.

Parameters

[out]	buffer	Cannot be NULL.
[in]	size	Must be > 0.
[in]	alignment	Power of 2 and >0 or OSAPI_ALIGNMENT_DEFAULT.

If the alignment is OSAPI_ALIGNMENT_DEFAULT, the returned pointer must have "default alignment" (meaning that any C-structure can start at the beginning of the buffer).

OSAPI_Heap_free_buffer()

OSPSLDllExport void OSAPI_Heap_free_buffer

(

void *

buffer

)

A static method to return a block (that was previously allocated with OSAPI_Heap_allocate_buffer) to the heap.

Parameters

[in]

buffer

If NULL, no op.