C API memory management definitions. More...

Classes
struct	os_memory_s
	Memory resource object storage. More...

Typedefs
typedef struct os_memory_s	os_memory_t
	Memory resource object storage.

Memory Management Functions
os_memory_t *	os_memory_get_default (void)
	Get the application default memory resource (free store).

void *	os_memory_allocate (os_memory_t *memory, size_t bytes, size_t alignment)
	Allocate a block of memory.

void	os_memory_deallocate (os_memory_t memory, void addr, size_t bytes, size_t alignment)
	Deallocate the previously allocated block of memory.

void	os_memory_reset (os_memory_t *memory)
	Reset the memory manager to the initial state.

bool	os_memory_coalesce (os_memory_t *memory)
	Coalesce free blocks.

size_t	os_memory_get_total_bytes (os_memory_t *memory)
	Get the total size of managed memory.

size_t	os_memory_get_allocated_bytes (os_memory_t *memory)
	Get the total size of allocated chunks.

size_t	os_memory_get_free_bytes (os_memory_t *memory)
	Get the total size of free chunks.

size_t	os_memory_get_allocated_chunks (os_memory_t *memory)
	Get the number of allocated chunks.

size_t	os_memory_get_free_chunks (os_memory_t *memory)
	Get the number of free chunks.

Standard functions
void *	malloc (size_t bytes)
	Allocate a memory block (non-initialised).

void *	calloc (size_t nelem, size_t elbytes)
	Allocate an array of memory blocks (initialised to zero).

void *	realloc (void *ptr, size_t bytes)
	Reallocate the memory block (non-initialised).

void	free (void *ptr)
	Free the allocated memory block.

Detailed Description

C API memory management definitions.

The µOS++ 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[])
{
  os_memory_t* mem;
 
  // Get the memory resource used to manage the application free store.
  mem = os_memory_get_default();
 
  void* p;
  p = os_memory_allocate(mem, 123, 8);
  os_memory_deallocate(mem, p, 123, 8);
 
  // Print some memory resource statistics.
  trace_printf("%u\n", os_memory_get_free_bytes(mem));
}

Typedef Documentation

◆ os_memory_t

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

◆ calloc()

void * calloc	(	size_t	nelem,
		size_t	elbytes
	)

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

Parameters

nelem	Number of elements.
elbytes	Element 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 µOS++ 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 151 of file malloc.cpp.

◆ free()

void free ( void * ptr )

Free the allocated memory block.

Parameters

ptr	Pointer 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 µOS++ 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 341 of file malloc.cpp.

◆ malloc()

void * malloc ( size_t bytes )

Allocate a memory block (non-initialised).

Parameters

bytes Number 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 µOS++ 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 84 of file malloc.cpp.

◆ os_memory_allocate()

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

Allocate a block of memory.

Parameters

memory	Pointer to a memory resource object instance.
bytes	Number of bytes to allocate.
alignment	Integer (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 3036 of file os-c-wrapper.cpp.

◆ os_memory_coalesce()

bool os_memory_coalesce ( os_memory_t * memory )

Coalesce free blocks.

Parameters

memory Pointer to a memory resource object instance.

Parameters: None.

Return values

true	if the operation resulted in larger blocks.
false	if 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 3090 of file os-c-wrapper.cpp.

◆ os_memory_deallocate()

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

Deallocate the previously allocated block of memory.

Parameters

memory	Pointer to a memory resource object instance.
addr	Address of memory block to free.
bytes	Number of bytes to deallocate (may be 0 if unknown).
alignment	Integer (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 3054 of file os-c-wrapper.cpp.

◆ os_memory_get_allocated_bytes()

size_t os_memory_get_allocated_bytes ( os_memory_t * memory )

Get the total size of allocated chunks.

Parameters

memory Pointer 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 3124 of file os-c-wrapper.cpp.

◆ os_memory_get_allocated_chunks()

size_t os_memory_get_allocated_chunks ( os_memory_t * memory )

Get the number of allocated chunks.

Parameters

memory Pointer 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 3158 of file os-c-wrapper.cpp.

◆ os_memory_get_default()

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 3023 of file os-c-wrapper.cpp.

◆ os_memory_get_free_bytes()

size_t os_memory_get_free_bytes ( os_memory_t * memory )

Get the total size of free chunks.

Parameters

memory Pointer 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 3141 of file os-c-wrapper.cpp.

◆ os_memory_get_free_chunks()

size_t os_memory_get_free_chunks ( os_memory_t * memory )

Get the number of free chunks.

Parameters

memory Pointer 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 3175 of file os-c-wrapper.cpp.

◆ os_memory_get_total_bytes()

size_t os_memory_get_total_bytes ( os_memory_t * memory )

Get the total size of managed memory.

Parameters

memory Pointer 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 3107 of file os-c-wrapper.cpp.

◆ os_memory_reset()

void os_memory_reset ( os_memory_t * memory )

Reset the memory manager to the initial state.

Parameters

memory Pointer 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 3073 of file os-c-wrapper.cpp.

◆ realloc()

void * realloc	(	void *	ptr,
		size_t	bytes
	)

Reallocate the memory block (non-initialised).

Parameters

ptr	Pointer to previously allocated block.
bytes	Number 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 µOS++ 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 250 of file malloc.cpp.

Classes

Typedefs

Memory Management Functions

Standard functions

Detailed Description

Typedef Documentation

◆ os_memory_t

Function Documentation

◆ calloc()

◆ free()

◆ malloc()

◆ os_memory_allocate()

◆ os_memory_coalesce()

◆ os_memory_deallocate()

◆ os_memory_get_allocated_bytes()

◆ os_memory_get_allocated_chunks()

◆ os_memory_get_default()

◆ os_memory_get_free_bytes()

◆ os_memory_get_free_chunks()

◆ os_memory_get_total_bytes()

◆ os_memory_reset()

◆ realloc()