µOS++ IIIe / CMSIS++ / POSIX++ Reference  v6.3.11
“Perfekt ist nicht gut genug”
The third edition of µOS++ and CMSIS++, a proposal for the next generation CMSIS, written in C++.
Memory management

C API memory management definitions. More...

Classes

struct  os_memory_s
 Memory resource object storage. More...
 

Types

typedef struct os_memory_s os_memory_t
 Memory resource object storage. More...
 

Memory Management Functions

os_memory_tos_memory_get_default (void)
 Get the application default memory resource (free store). More...
 
void * os_memory_allocate (os_memory_t *memory, size_t bytes, size_t alignment)
 Allocate a block of memory. More...
 
void os_memory_deallocate (os_memory_t *memory, void *addr, size_t bytes, size_t alignment)
 Deallocate the previously allocated block of memory. More...
 
void os_memory_reset (os_memory_t *memory)
 Reset the memory manager to the initial state. More...
 
bool os_memory_coalesce (os_memory_t *memory)
 Coalesce free blocks. More...
 
size_t os_memory_get_total_bytes (os_memory_t *memory)
 Get the total size of managed memory. More...
 
size_t os_memory_get_allocated_bytes (os_memory_t *memory)
 Get the total size of allocated chunks. More...
 
size_t os_memory_get_free_bytes (os_memory_t *memory)
 Get the total size of free chunks. More...
 
size_t os_memory_get_allocated_chunks (os_memory_t *memory)
 Get the number of allocated chunks. More...
 
size_t os_memory_get_free_chunks (os_memory_t *memory)
 Get the number of free chunks. More...
 

Standard functions

void * malloc (size_t bytes)
 Allocate a memory block (non-initialised). More...
 
void * calloc (size_t nelem, size_t elbytes)
 Allocate an array of memory blocks (initialised to zero). More...
 
void * realloc (void *ptr, size_t bytes)
 Reallocate the memory block (non-initialised). More...
 
void free (void *ptr)
 Free the allocated memory block. More...
 

Detailed Description

C API memory management definitions.

The CMSIS++ RTOS includes several advanced and flexible memory management features.

Access to these classes from C can be done using the os_memory_*() functions.

For the complete definition, see
RTOS C++ API
Examples
int
os_main (int argc, char* argv[])
{
// Get the memory resource used to manage the application free store.
void* p;
p = os_memory_allocate(mem, 123, 8);
os_memory_deallocate(mem, p, 123, 8);
// Print some memory resource statistics.
}

Types

typedef struct os_memory_s os_memory_t

Memory resource object storage.

A pointer to this structure can be used as a pointer to the os::rtos::memory::memory_resource object.

The members of this structure are hidden and should not be used directly, but only through specific functions.

See also
os::rtos::memory::memory_resource

Function Documentation

void* calloc ( size_t  nelem,
size_t  elbytes 
)

Allocate an array of memory blocks (initialised to zero).

Parameters
nelemNumber of elements.
elbytesElement size in bytes.
Returns
A pointer to the allocated memory or null and ENOMEM.

The calloc() function shall allocate unused space for an array of nelem elements each of whose size in bytes is elbytes. The space shall be initialised to all bits 0.

The order and contiguity of storage allocated by successive calls to calloc() is unspecified. The pointer returned if the allocation succeeds shall be suitably aligned so that it may be assigned to a pointer to any type of object and then used to access such an object or an array of such objects in the space allocated (until the space is explicitly freed or reallocated). Each such allocation shall yield a pointer to an object disjoint from any other object. The pointer returned shall point to the start (lowest byte address) of the allocated space. If the space cannot be allocated, a null pointer shall be returned. If the size of the space requested is 0, the behaviour is implementation-defined: the value returned shall be either a null pointer or a unique pointer.

Upon successful completion with both nelem and elbytes non-zero, calloc() shall return a pointer to the allocated space. If either nelem or elbytes is 0, then either a null pointer or a unique pointer value that can be successfully passed to free() shall be returned. Otherwise, it shall return a null pointer and set errno to indicate the error.

Note
In CMSIS++ this function uses a scheduler critical section and is thread safe.
POSIX compatibility
Inspired by calloc() (IEEE Std 1003.1, 2013 Edition).
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 162 of file malloc.cpp.

void free ( void *  ptr)

Free the allocated memory block.

Parameters
ptrPointer to previously allocated block.
Returns
Nothing.

The free() function shall cause the space pointed to by ptr to be deallocated; that is, made available for further allocation. If ptr is a null pointer, no action shall occur. Otherwise, if the argument does not match a pointer earlier returned by a function in POSIX.1-2008 that allocates memory as if by malloc(), or if the space has been deallocated by a call to free() or realloc(), the behaviour is undefined.

Any use of a pointer that refers to freed space results in undefined behaviour.

The free() function shall not return a value.

Note
In CMSIS++ this function uses a scheduler critical section and is thread safe.
POSIX compatibility
Inspired by free() (IEEE Std 1003.1, 2013 Edition).
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 352 of file malloc.cpp.

void* malloc ( size_t  bytes)

Allocate a memory block (non-initialised).

Parameters
bytesNumber of bytes to allocate.
Returns
A pointer to the allocated memory or null and ENOMEM.

The malloc() function shall allocate unused space for an object whose size is bytes and whose value is unspecified.

The order and contiguity of storage allocated by successive calls to malloc() is unspecified. The pointer returned if the allocation succeeds shall be suitably aligned so that it may be assigned to a pointer to any type of object and then used to access such an object in the space allocated (until the space is explicitly freed or reallocated). Each such allocation shall yield a pointer to an object disjoint from any other object. The pointer returned points to the start (lowest byte address) of the allocated space. If the space cannot be allocated, a null pointer shall be returned. If the size of the space requested is 0, the behaviour is implementation-defined: the value returned shall be either a null pointer or a unique pointer.

Upon successful completion with size not equal to 0, malloc() shall return a pointer to the allocated space. If size is 0, either a null pointer or a unique pointer that can be successfully passed to free() shall be returned. Otherwise, it shall return a null pointer and set errno to indicate the error.

Note
In CMSIS++ this function uses a scheduler critical section and is thread safe.
POSIX compatibility
Inspired by malloc() (IEEE Std 1003.1, 2013 Edition).
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 95 of file malloc.cpp.

void* os_memory_allocate ( os_memory_t memory,
size_t  bytes,
size_t  alignment 
)

Allocate a block of memory.

Parameters
memoryPointer to a memory resource object instance.
bytesNumber of bytes to allocate.
alignmentInteger (power of 2) with alignment constraints.
Warning
Cannot be invoked from Interrupt Service Routines.
Not thread safe, use a scheduler critical section to protect it.
For the complete definition, see
os::rtos::memory::memory_resource::allocate()

Definition at line 3328 of file os-c-wrapper.cpp.

bool os_memory_coalesce ( os_memory_t memory)

Coalesce free blocks.

Parameters
memoryPointer to a memory resource object instance.
Parameters
None.
Return values
trueif the operation resulted in larger blocks.
falseif the operation was ineffective.
Warning
Cannot be invoked from Interrupt Service Routines.
Not thread safe, use a scheduler critical section to protect it.
For the complete definition, see
os::rtos::memory::memory_resource::coalesce()

Definition at line 3379 of file os-c-wrapper.cpp.

void os_memory_deallocate ( os_memory_t memory,
void *  addr,
size_t  bytes,
size_t  alignment 
)

Deallocate the previously allocated block of memory.

Parameters
memoryPointer to a memory resource object instance.
addrAddress of memory block to free.
bytesNumber of bytes to deallocate (may be 0 if unknown).
alignmentInteger (power of 2) with alignment constraints.
Warning
Cannot be invoked from Interrupt Service Routines.
Not thread safe, use a scheduler critical section to protect it.
For the complete definition, see
os::rtos::memory::memory_resource::deallocate()

Definition at line 3345 of file os-c-wrapper.cpp.

size_t os_memory_get_allocated_bytes ( os_memory_t memory)

Get the total size of allocated chunks.

Parameters
memoryPointer to a memory resource object instance.
Returns
Number of bytes.
Warning
Cannot be invoked from Interrupt Service Routines.
Not thread safe, use a scheduler critical section to protect it.
For the complete definition, see
os::rtos::memory::memory_resource::allocated_bytes()

Definition at line 3411 of file os-c-wrapper.cpp.

size_t os_memory_get_allocated_chunks ( os_memory_t memory)

Get the number of allocated chunks.

Parameters
memoryPointer to a memory resource object instance.
Returns
Number of chunks.
Warning
Cannot be invoked from Interrupt Service Routines.
Not thread safe, use a scheduler critical section to protect it.
For the complete definition, see
os::rtos::memory::memory_resource::allocated_chunks()

Definition at line 3443 of file os-c-wrapper.cpp.

os_memory_t* os_memory_get_default ( void  )

Get the application default memory resource (free store).

Returns
Pointer to memory resource object instance.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::memory::get_default_resource()

Definition at line 3313 of file os-c-wrapper.cpp.

size_t os_memory_get_free_bytes ( os_memory_t memory)

Get the total size of free chunks.

Parameters
memoryPointer to a memory resource object instance.
Returns
Number of bytes.
Warning
Cannot be invoked from Interrupt Service Routines.
Not thread safe, use a scheduler critical section to protect it.
For the complete definition, see
os::rtos::memory::memory_resource::free_bytes()

Definition at line 3427 of file os-c-wrapper.cpp.

size_t os_memory_get_free_chunks ( os_memory_t memory)

Get the number of free chunks.

Parameters
memoryPointer to a memory resource object instance.
Returns
Number of chunks.
Warning
Cannot be invoked from Interrupt Service Routines.
Not thread safe, use a scheduler critical section to protect it.
For the complete definition, see
os::rtos::memory::memory_resource::free_chunks()

Definition at line 3459 of file os-c-wrapper.cpp.

size_t os_memory_get_total_bytes ( os_memory_t memory)

Get the total size of managed memory.

Parameters
memoryPointer to a memory resource object instance.
Returns
Number of bytes.
Warning
Cannot be invoked from Interrupt Service Routines.
Not thread safe, use a scheduler critical section to protect it.
For the complete definition, see
os::rtos::memory::memory_resource::total_bytes()

Definition at line 3395 of file os-c-wrapper.cpp.

void os_memory_reset ( os_memory_t memory)

Reset the memory manager to the initial state.

Parameters
memoryPointer to a memory resource object instance.
Parameters
None.
Returns
Nothing.
Warning
Cannot be invoked from Interrupt Service Routines.
Not thread safe, use a scheduler critical section to protect it.
For the complete definition, see
os::rtos::memory::memory_resource::reset()

Definition at line 3363 of file os-c-wrapper.cpp.

void* realloc ( void *  ptr,
size_t  bytes 
)

Reallocate the memory block (non-initialised).

Parameters
ptrPointer to previously allocated block.
bytesNumber of bytes to re-allocate.
Returns
A pointer to the allocated memory or null and ENOMEM.

The realloc() function shall deallocate the old object pointed to by ptr and return a pointer to a new object that has the size specified by bytes. The contents of the new object shall be the same as that of the old object prior to deallocation, up to the lesser of the new and old sizes. Any bytes in the new object beyond the size of the old object have indeterminate values. If the size of the space requested is zero, the behaviour shall be implementation-defined: either a null pointer is returned, or the behavior shall be as if the size were some non-zero value, except that the returned pointer shall not be used to access an object. If the space cannot be allocated, the object shall remain unchanged.

If ptr is a null pointer, realloc() shall be equivalent to malloc() for the specified size.

If ptr does not match a pointer returned earlier by calloc(), malloc(), or realloc() or if the space has previously been deallocated by a call to free() or realloc(), the behaviour is undefined.

The order and contiguity of storage allocated by successive calls to realloc() is unspecified. The pointer returned if the allocation succeeds shall be suitably aligned so that it may be assigned to a pointer to any type of object and then used to access such an object in the space allocated (until the space is explicitly freed or reallocated). Each such allocation shall yield a pointer to an object disjoint from any other object. The pointer returned shall point to the start (lowest byte address) of the allocated space. If the space cannot be allocated, a null pointer shall be returned.

Upon successful completion, realloc() shall return a pointer to the (possibly moved) allocated space. If size is 0, either:

  • A null pointer shall be returned and errno set to an implementation-defined value.
  • A unique pointer that can be successfully passed to free() shall be returned, and the memory object pointed to by ptr shall be freed. The application shall ensure that the pointer is not used to access an object.

If there is not enough available memory, realloc() shall return a null pointer and set errno to ENOMEM. If realloc() returns a null pointer and errno has been set to ENOMEM, the memory referenced by ptr shall not be changed.

Note
In CMSIS++ this function uses a scheduler critical section and is thread safe.
POSIX compatibility
Inspired by realloc() (IEEE Std 1003.1, 2013 Edition).
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 261 of file malloc.cpp.