OSAPI Heap

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.
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.
void	OSAPI_Heap_allocate_struct (TYPE **pointer, TYPE)
	Allocates space on the heap for a C structure and initializes the structure with 0's.
void	OSAPI_Heap_free_struct (TYPE *pointer)
	Returns previously allocated (with OSAPI_Heap_allocate_struct) space to the heap.
void	OSAPI_Heap_allocate_array (TYPE **pointer, int count, TYPE)
	A static method to allocate space on the heap for an array of C structures; the array is initialized with 0's.
void	OSAPI_Heap_free_array (TYPE *storage)
	A static method to return space (that was previously allocated with OSAPI_Heap_allocate_array) to the heap.
void	OSAPI_Heap_allocate_string (char **pointer, RTI_UINT32 size)
	A static method to allocate space on the heap for a string of up to a given size. The string is initialized with 0's.
void	OSAPI_Heap_free_string (char *pointer)
	A static method to return space string space to the heap.
void	OSAPI_Heap_allocate_buffer (char **buffer, RTI_SIZE_T size, OSAPI_Alignment_T alignment)
	A static method to allocate a block of memory of the provided size from the heap.
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.
RTI_SIZE_T	OSAPI_Heap_get_allocated_byte_count (void)
	Return current allocated memory.
void	OSAPI_Heap_disable_alloc (void)
	Disable memory allocation.

Variables
RTI_SIZE_T	OSAPI_gv_AllocatedByteCount
	Current allocated bytes.

---

Detailed Description

---

Typedef Documentation

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

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

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

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

void OSAPI_Heap_allocate_struct	(	TYPE **	pointer,
		TYPE
	)

Allocates space on the heap for a C structure and initializes the structure with 0's.

Example:

    struct MyStruct *myStruct;
    OSAPI_Heap_allocate_struct(&myStruct, struct MyStruct);
    if (myStruct==NULL) {
        return;
    }

The returned space must be freed with OSAPI_Heap_free_struct.

NOTE: This operation is implemented as a macro in order to support the specification of a "type" argument (converted to a size value using the sizeof operator).

void OSAPI_Heap_free_struct

(

TYPE *

pointer

)

Returns previously allocated (with OSAPI_Heap_allocate_struct) space to the heap.

Parameters:

[in]

pointer

If NULL, no op.

Example:

    char *c;
    OSAPI_Heap_allocate_struct(&c, char);
    OSAPI_Heap_free_struct(c);

void OSAPI_Heap_allocate_array	(	TYPE **	pointer,
		int	count,
		TYPE
	)

A static method to allocate space on the heap for an array of C structures; the array is initialized with 0's.

Example:

    struct MyElement *array;
    OSAPI_Heap_allocate_struct(&array, 7, struct MyElement);
    if (array==NULL) {
        return;
    }
    // elements of the array can be accessed as array[i]

The returned space must be freed with OSAPI_Heap_free_array.

NOTE: This operation is implemented as a macro in order to support the specification of a "type" argument (converted to a size value using the sizeof operator).

void OSAPI_Heap_free_array

(

TYPE *

storage

)

A static method to return space (that was previously allocated with OSAPI_Heap_allocate_array) to the heap.

Example:

    char *c;
    OSAPI_Heap_allocate_array(&c, 1, char);
    OSAPI_Heap_free_array(c);

Parameters:

[in]

storage

If NULL, no op.

void OSAPI_Heap_allocate_string	(	char **	pointer,
		RTI_UINT32	size
	)

A static method to allocate space on the heap for a string of up to a given size. The string is initialized with 0's.

Example:

    char* myString;
    OSAPI_Heap_allocate_string(&myString, 128);

Parameters:

[out]	pointer	String buffer.
[in]	size	Size in bytes to allocate; this length must not include the string terminator, which is automatically added to the specified value.

The returned space must be freed with OSAPI_Heap_free_string.

void OSAPI_Heap_free_string

(

char *

pointer

)

A static method to return space string space to the heap.

Parameters:

[in]

pointer

If NULL, no op.

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

A static method to allocate a block of memory of the provided size from the heap.

Postcondition:

The returned address will be a multiple of 2^alignment; its memory will be initialized with 0's.

Parameters:

[out]	buffer
[in]	size	> 0
[in]	alignment	Power of 2 and >0 or OSAPI_ALIGNMENT_DEFAULT. If the alignment is OSAPI_ALIGNMENT_DEFAULT, the returned pointer will have "default alignment" (meaning that any C-structure can start at the beginning of the buffer).

The block must be returned to the heap with OSAPI_Heap_free_buffer.

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.

RTI_SIZE_T OSAPI_Heap_get_allocated_byte_count

(

void

)

Return current allocated memory.

MT Safety:

UNSAFE

void OSAPI_Heap_disable_alloc

(

void

)

Disable memory allocation.

---

Variable Documentation

RTI_SIZE_T OSAPI_gv_AllocatedByteCount

Current allocated bytes.