Memory management

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

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

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
	)

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 153 of file malloc.cpp.

{
  assert (!rtos::interrupts::in_handler_mode ());
 
  errno = 0;
  if (nelem == 0 || elbytes == 0)
    {
      return nullptr;
    }
 
  void* mem;
  {
    // ----- Begin of critical section ----------------------------------------
    rtos::scheduler::critical_section scs;
 
    mem = estd::pmr::get_default_resource ()->allocate (nelem * elbytes);
 
#if defined(OS_TRACE_LIBC_MALLOC)
    trace::printf ("::%s(%u,%u)=%p\n", __func__, nelem, elbytes, mem);
#endif
    // ----- End of critical section ------------------------------------------
  }
 
  if (mem != nullptr)
    {
      memset (mem, 0, nelem * elbytes);
    }
  else
    {
      errno = ENOMEM;
    }
 
  return mem;
}

References os::rtos::memory::memory_resource::allocate(), os::estd::pmr::get_default_resource(), os::rtos::interrupts::in_handler_mode(), and os::trace::printf().

free()

void free

(

void *

ptr

)

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 347 of file malloc.cpp.

{
  assert (!rtos::interrupts::in_handler_mode ());
 
  if (ptr == nullptr)
    {
      return;
    }
 
  // ----- Begin of critical section ------------------------------------------
  rtos::scheduler::critical_section scs;
 
#if defined(OS_TRACE_LIBC_MALLOC)
  trace::printf ("::%s(%p)\n", __func__, ptr);
#endif
 
  // Size unknown, pass 0.
  estd::pmr::get_default_resource ()->deallocate (ptr, 0);
  // ----- End of critical section --------------------------------------------
}

References os::rtos::memory::memory_resource::deallocate(), os::estd::pmr::get_default_resource(), os::rtos::interrupts::in_handler_mode(), and os::trace::printf().

Referenced by os_mempool_free().

malloc()

void * malloc

(

size_t

bytes

)

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.

{
  assert (!rtos::interrupts::in_handler_mode ());
 
  void* mem;
  {
    // ----- Begin of critical section --------------------------------------
    rtos::scheduler::critical_section scs;
 
    errno = 0;
    mem = estd::pmr::get_default_resource ()->allocate (bytes);
    if (mem == nullptr)
      {
        errno = ENOMEM;
      }
 
#if defined(OS_TRACE_LIBC_MALLOC)
    trace::printf ("::%s(%d)=%p\n", __func__, bytes, mem);
#endif
    // ----- End of critical section ----------------------------------------
  }
 
  return mem;
}

References os::rtos::memory::memory_resource::allocate(), os::estd::pmr::get_default_resource(), os::rtos::interrupts::in_handler_mode(), and os::trace::printf().

os_memory_allocate()

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

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

{
  assert (memory != nullptr);
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wcast-align"
  return (reinterpret_cast<rtos::memory::memory_resource&> (*memory))
      .allocate (bytes, alignment);
#pragma GCC diagnostic pop
}

os_memory_coalesce()

bool os_memory_coalesce

(

os_memory_t *

memory

)

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

{
  assert (memory != nullptr);
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wcast-align"
  return (reinterpret_cast<rtos::memory::memory_resource&> (*memory))
      .coalesce ();
#pragma GCC diagnostic pop
}

os_memory_deallocate()

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

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

{
  assert (memory != nullptr);
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wcast-align"
  (reinterpret_cast<rtos::memory::memory_resource&> (*memory))
      .deallocate (addr, bytes, alignment);
#pragma GCC diagnostic pop
}

os_memory_get_allocated_bytes()

size_t os_memory_get_allocated_bytes

(

os_memory_t *

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::allocated_bytes()

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

{
  assert (memory != nullptr);
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wcast-align"
  return (reinterpret_cast<rtos::memory::memory_resource&> (*memory))
      .allocated_bytes ();
#pragma GCC diagnostic pop
}

os_memory_get_allocated_chunks()

size_t os_memory_get_allocated_chunks

(

os_memory_t *

memory

)

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

{
  assert (memory != nullptr);
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wcast-align"
  return (reinterpret_cast<rtos::memory::memory_resource&> (*memory))
      .allocated_chunks ();
#pragma GCC diagnostic pop
}

os_memory_get_default()

os_memory_t * os_memory_get_default

(

void

)

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

{
  return reinterpret_cast<os_memory_t*> (
      rtos::memory::get_default_resource ());
}

References os::rtos::memory::get_default_resource().

os_memory_get_free_bytes()

size_t os_memory_get_free_bytes

(

os_memory_t *

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::free_bytes()

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

{
  assert (memory != nullptr);
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wcast-align"
  return (reinterpret_cast<rtos::memory::memory_resource&> (*memory))
      .free_bytes ();
#pragma GCC diagnostic pop
}

os_memory_get_free_chunks()

size_t os_memory_get_free_chunks

(

os_memory_t *

memory

)

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

{
  assert (memory != nullptr);
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wcast-align"
  return (reinterpret_cast<rtos::memory::memory_resource&> (*memory))
      .free_chunks ();
#pragma GCC diagnostic pop
}

os_memory_get_total_bytes()

size_t os_memory_get_total_bytes

(

os_memory_t *

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

{
  assert (memory != nullptr);
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wcast-align"
  return (reinterpret_cast<rtos::memory::memory_resource&> (*memory))
      .total_bytes ();
#pragma GCC diagnostic pop
}

os_memory_reset()

void os_memory_reset

(

os_memory_t *

memory

)

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

{
  assert (memory != nullptr);
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wcast-align"
  (reinterpret_cast<rtos::memory::memory_resource&> (*memory)).reset ();
#pragma GCC diagnostic pop
}

realloc()

void * realloc	(	void *	ptr,
		size_t	bytes
	)

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 254 of file malloc.cpp.

{
  assert (!rtos::interrupts::in_handler_mode ());
 
  void* mem;
 
  {
    // ----- Begin of critical section ----------------------------------------
    rtos::scheduler::critical_section scs;
 
    errno = 0;
    if (ptr == nullptr)
      {
        mem = estd::pmr::get_default_resource ()->allocate (bytes);
#if defined(OS_TRACE_LIBC_MALLOC)
        trace::printf ("::%s(%p,%u)=%p\n", __func__, ptr, bytes, mem);
#endif
        if (mem == nullptr)
          {
            errno = ENOMEM;
          }
        return mem;
      }
 
    if (bytes == 0)
      {
        estd::pmr::get_default_resource ()->deallocate (ptr, 0);
#if defined(OS_TRACE_LIBC_MALLOC)
        trace::printf ("::%s(%p,%u)=0\n", __func__, ptr, bytes);
#endif
        return nullptr;
      }
 
#if 0
      /* TODO: There is chance to shrink the chunk if newly requested
       * size is much small */
      if (nano_malloc_usable_size (RCALL ptr) >= bytes)
      return ptr;
#endif
 
    mem = estd::pmr::get_default_resource ()->allocate (bytes);
    if (mem != nullptr)
      {
        memcpy (mem, ptr, bytes);
        estd::pmr::get_default_resource ()->deallocate (ptr, 0);
      }
    else
      {
        errno = ENOMEM;
      }
 
#if defined(OS_TRACE_LIBC_MALLOC)
    trace::printf ("::%s(%p,%u)=%p", __func__, ptr, bytes, mem);
#endif
    // ----- End of critical section ------------------------------------------
  }
 
  return mem;
}

References os::rtos::memory::memory_resource::allocate(), os::rtos::memory::memory_resource::deallocate(), os::estd::pmr::get_default_resource(), os::rtos::interrupts::in_handler_mode(), and os::trace::printf().