RTI Connext DDS Micro C API  Version 3.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Macros | Typedefs | Functions | Variables
OSAPI Heap
OS API

Macros

#define OSAPI_get_alignment_of(testType)   offsetof (struct { char c; testType member; }, member)
 Gets alignment of a type.
#define OSAPI_Heap_is_address_aligned(location, alignment)   (((char*)(location) - (char*) 0) % (alignment) == 0)
 Check if a particular address is aligned to an alignment.
#define OSAPI_Heap_align_size_up(size, alignment)   (((size) + ((alignment) - 1U)) & (~((alignment) - 1U)))
 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.
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 (MACRO_TYPE **pointer, MACRO_TYPE)
 Allocates space on the heap for a C structure and initializes the structure with 0's.
void OSAPI_Heap_free_struct (MACRO_TYPE *pointer)
 Returns previously allocated (with OSAPI_Heap_allocate_struct) space to the heap.
void OSAPI_Heap_allocate_array (MACRO_TYPE **pointer, int count, MACRO_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 (MACRO_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

Macro Definition Documentation

#define OSAPI_get_alignment_of (   testType)    offsetof (struct { char c; testType member; }, member)

Gets alignment of a type.

#define OSAPI_Heap_is_address_aligned (   location,
  alignment 
)    (((char*)(location) - (char*) 0) % (alignment) == 0)

Check if a particular address is aligned to an alignment.

#define OSAPI_Heap_align_size_up (   size,
  alignment 
)    (((size) + ((alignment) - 1U)) & (~((alignment) - 1U)))

Aligns a particular address to an alignment alignment.

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]countThe number of elements to allocate.
[in]sizeThe 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]ptrCurrently allocated buffer
[in]sizeThe 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]ptrPointer to region previous allocated with OSAPI_Heap_allocate
See also:
OSAPI_Heap_allocate
void OSAPI_Heap_allocate_struct ( MACRO_TYPE **  pointer,
MACRO_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 ( MACRO_TYPE *  pointer)

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

Parameters:
[in]pointerIf NULL, no op.

Example:

char *c;
OSAPI_Heap_allocate_struct(&c, char);
OSAPI_Heap_free_struct(c);
void OSAPI_Heap_allocate_array ( MACRO_TYPE **  pointer,
int  count,
MACRO_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 ( MACRO_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]storageIf 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]pointerString buffer.
[in]sizeSize 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]pointerIf 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]alignmentPower 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]bufferIf 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.

RTI Connext DDS Micro C API Version 3.0.0 Copyright © Fri Mar 22 2019 Real-Time Innovations, Inc