Xenomai  3.1
Heap management services

Region of memory dedicated to real-time allocation. More...

Collaboration diagram for Heap management services:

Data Structures

struct  RT_HEAP_INFO
 Heap status descriptor. More...
 

Macros

#define H_PRIO   0x1 /* Pend by task priority order. */
 Creation flags. More...
 

Functions

int rt_heap_create (RT_HEAP *heap, const char *name, size_t heapsize, int mode)
 
Create a heap. More...
 
int rt_heap_delete (RT_HEAP *heap)
 
Delete a heap. More...
 
int rt_heap_alloc_timed (RT_HEAP *heap, size_t size, const struct timespec *abs_timeout, void **blockp)
 
Allocate a block from a heap. More...
 
static int rt_heap_alloc_until (RT_HEAP *heap, size_t size, RTIME timeout, void **blockp)
 
Allocate a block from a heap (with absolute scalar timeout). More...
 
static int rt_heap_alloc (RT_HEAP *heap, size_t size, RTIME timeout, void **blockp)
 
Allocate a block from a heap (with relative scalar timeout). More...
 
int rt_heap_free (RT_HEAP *heap, void *block)
 
Release a block to a heap. More...
 
int rt_heap_inquire (RT_HEAP *heap, RT_HEAP_INFO *info)
 
Query heap status. More...
 
int rt_heap_bind (RT_HEAP *heap, const char *name, RTIME timeout)
 
Bind to a heap. More...
 
int rt_heap_unbind (RT_HEAP *heap)
 
Unbind from a heap. More...
 

Detailed Description

Region of memory dedicated to real-time allocation.

Heaps are regions of memory used for dynamic memory allocation in a time-bounded fashion. Blocks of memory are allocated and freed in an arbitrary order and the pattern of allocation and size of blocks is not known until run time.

Macro Definition Documentation

◆ H_PRIO

#define H_PRIO   0x1 /* Pend by task priority order. */

Creation flags.

Referenced by rt_heap_create().

Function Documentation

◆ rt_heap_alloc()

int rt_heap_alloc ( RT_HEAP *  heap,
size_t  size,
RTIME  timeout,
void **  blockp 
)
inlinestatic


Allocate a block from a heap (with relative scalar timeout).

This routine is a variant of rt_heap_alloc_timed() accepting a relative timeout specification expressed as a scalar value. Passing TM_INFINITE in timeout causes the caller to block indefinitely until a block is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case a block is not available.

Tags
xthread-nowait, switch-primary

◆ rt_heap_alloc_timed()

int rt_heap_alloc_timed ( RT_HEAP *  heap,
size_t  size,
const struct timespec *  abs_timeout,
void **  blockp 
)


Allocate a block from a heap.

This service allocates a block from a given heap, or returns the address of the single memory segment if H_SINGLE was mentioned in the creation mode to rt_heap_create(). When not enough memory is available on entry to this service, tasks may be blocked until their allocation request can be fulfilled.

Parameters
heapThe heap descriptor.
sizeThe requested size (in bytes) of the block. If the heap is managed as a single-block area (H_SINGLE), this value can be either zero, or the same value given to rt_heap_create(). In that case, the same block covering the entire heap space is returned to all callers of this service.
abs_timeoutAn absolute date expressed in clock ticks, specifying a time limit to wait for a block of the requested size to be available from the heap (see note). Passing NULL causes the caller to block indefinitely until a block is available. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service to return immediately without blocking in case a block is not available.
blockpA pointer to a memory location which will be written upon success with the address of the allocated block, or the start address of the single memory segment. In the former case, the block can be freed using rt_heap_free().
Returns
Zero is returned upon success. Otherwise:
  • -ETIMEDOUT is returned if abs_timeout is reached before a block is available.
  • -EWOULDBLOCK is returned if abs_timeout is equal to { .tv_sec = 0, .tv_nsec = 0 } and no block is immediately available on entry to fulfill the allocation request.
  • -EINTR is returned if rt_task_unblock() was called for the current task before a block became available.
  • -EINVAL is returned if heap is not a valid heap descriptor, or heap is managed as a single-block area (i.e. H_SINGLE mode) and size is non-zero but does not match the original heap size passed to rt_heap_create().
  • -EIDRM is returned if heap is deleted while the caller was waiting for a block. In such event, heap is no more valid upon return of this service.
  • -EPERM is returned if this service should block, but was not called from a Xenomai thread.
Tags
xthread-nowait, switch-primary
Note
If shared multi-processing is enabled (i.e. –enable-pshared was passed to the configure script), requests for a block size larger than twice the allocation page size are rounded up to the next page size. The allocation page size is currently 512 bytes long (HOBJ_PAGE_SIZE), which means that any request larger than 1k will be rounded up to the next 512 byte boundary.
abs_timeout is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

◆ rt_heap_alloc_until()

int rt_heap_alloc_until ( RT_HEAP *  heap,
size_t  size,
RTIME  abs_timeout,
void **  blockp 
)
inlinestatic


Allocate a block from a heap (with absolute scalar timeout).

This routine is a variant of rt_heap_alloc_timed() accepting an absolute timeout specification expressed as a scalar value. Passing TM_INFINITE in timeout causes the caller to block indefinitely until a block is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case a block is not available.

Tags
xthread-nowait, switch-primary

◆ rt_heap_bind()

int rt_heap_bind ( RT_HEAP *  heap,
const char *  name,
RTIME  timeout 
)


Bind to a heap.

This routine creates a new descriptor to refer to an existing heap identified by its symbolic name. If the object does not exist on entry, the caller may block until a heap of the given name is created.

Parameters
heapThe address of a heap descriptor filled in by the operation. Contents of this memory is undefined upon failure.
nameA valid NULL-terminated name which identifies the heap to bind to. This string should match the object name argument passed to rt_heap_create().
timeoutThe number of clock ticks to wait for the registration to occur (see note). Passing TM_INFINITE causes the caller to block indefinitely until the object is registered. Passing TM_NONBLOCK causes the service to return immediately without waiting if the object is not registered on entry.
Returns
Zero is returned upon success. Otherwise:
  • -EINTR is returned if rt_task_unblock() was called for the current task before the retrieval has completed.
  • -EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and the searched object is not registered on entry.
  • -ETIMEDOUT is returned if the object cannot be retrieved within the specified amount of time.
  • -EPERM is returned if this service should block, but was not called from a Xenomai thread.
Tags
xthread-nowait, switch-primary
Note
The timeout value is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

◆ rt_heap_create()

int rt_heap_create ( RT_HEAP *  heap,
const char *  name,
size_t  heapsz,
int  mode 
)


Create a heap.

This routine creates a memory heap suitable for time-bounded allocation requests of RAM chunks. When not enough memory is available, tasks may be blocked until their allocation request can be fulfilled.

By default, heaps support allocation of multiple blocks of memory in an arbitrary order. However, it is possible to ask for single-block management by passing the H_SINGLE flag into the mode parameter, in which case the entire memory space managed by the heap is made available as a unique block. In this mode, all allocation requests made through rt_heap_alloc() will return the same block address, pointing at the beginning of the heap memory.

Parameters
heapThe address of a heap descriptor which can be later used to identify uniquely the created object, upon success of this call.
nameAn ASCII string standing for the symbolic name of the heap. When non-NULL and non-empty, a copy of this string is used for indexing the created heap into the object registry.
heapszThe size (in bytes) of the memory pool, blocks will be claimed and released to. This area is not extensible, so this value must be compatible with the highest memory pressure that could be expected. The valid range is between 1 byte and 2Gb.
modeThe heap creation mode. The following flags can be OR'ed into this bitmask, each of them affecting the new heap:
  • H_FIFO makes tasks pend in FIFO order on the heap when waiting for available blocks.
  • H_PRIO makes tasks pend in priority order on the heap when waiting for available blocks.
  • H_SINGLE causes the entire heap space to be managed as a single memory block.
Returns
Zero is returned upon success. Otherwise:
  • -EINVAL is returned if mode is invalid, or heapsz is zero or larger than 2Gb.
  • -ENOMEM is returned if the system fails to get memory from the main heap in order to create the heap.
  • -EEXIST is returned if the name is conflicting with an already registered heap.
  • -EPERM is returned if this service was called from an invalid context, e.g. interrupt or non-Xenomai thread.
Tags
xthread-only, mode-unrestricted, switch-secondary
Note
Heaps can be shared by multiple processes which belong to the same Xenomai session.

References H_PRIO.

◆ rt_heap_delete()

int rt_heap_delete ( RT_HEAP *  heap)


Delete a heap.

This routine deletes a heap object previously created by a call to rt_heap_create(), releasing all tasks currently blocked on it.

Parameters
heapThe heap descriptor.
Returns
Zero is returned upon success. Otherwise:
  • -EINVAL is returned if heap is not a valid heap descriptor.
  • -EPERM is returned if this service was called from an asynchronous context.
Tags
mode-unrestricted, switch-secondary

◆ rt_heap_free()

int rt_heap_free ( RT_HEAP *  heap,
void *  block 
)


Release a block to a heap.

This service should be used to release a block to the heap it belongs to. An attempt to fulfill the request of every task blocked on rt_heap_alloc() is made once block is returned to the memory pool.

Parameters
heapThe heap descriptor.
blockThe address of the block to free.
Returns
Zero is returned upon success. Otherwise:
  • -EINVAL is returned if heap is not a valid heap descriptor, or block is not a valid block previously allocated by the rt_heap_alloc() service from heap.
Tags
unrestricted, switch-primary

◆ rt_heap_inquire()

int rt_heap_inquire ( RT_HEAP *  heap,
RT_HEAP_INFO info 
)


Query heap status.

This routine returns the status information about heap.

Parameters
heapThe heap descriptor.
infoA pointer to the return buffer" to copy the information to.
Returns
Zero is returned and status information is written to the structure pointed at by info upon success. Otherwise:
  • -EINVAL is returned if heap is not a valid heap descriptor.
Tags
unrestricted, switch-primary

◆ rt_heap_unbind()

int rt_heap_unbind ( RT_HEAP *  heap)


Unbind from a heap.

Parameters
heapThe heap descriptor.

This routine releases a previous binding to a heap. After this call has returned, the descriptor is no more valid for referencing this object.

Tags
thread-unrestricted