rcutils  master
C API providing common utilities and data structures.
Classes | Macros | Typedefs | Functions
allocator.h File Reference
#include <stdbool.h>
#include <stddef.h>
#include "rcutils/macros.h"
#include "rcutils/types/rcutils_ret.h"
#include "rcutils/visibility_control.h"

Go to the source code of this file.

Classes

struct  rcutils_allocator_t
 Encapsulation of an allocator. More...
 

Macros

#define RCUTILS_CHECK_ALLOCATOR(allocator, fail_statement)
 
#define RCUTILS_CHECK_ALLOCATOR_WITH_MSG(allocator, msg, fail_statement)
 

Typedefs

typedef struct rcutils_allocator_t rcutils_allocator_t
 Encapsulation of an allocator. More...
 

Functions

rcutils_allocator_t rcutils_get_zero_initialized_allocator (void)
 Return a zero initialized allocator. More...
 
rcutils_allocator_t rcutils_get_default_allocator (void)
 Return a properly initialized rcutils_allocator_t with default values. More...
 
bool rcutils_allocator_is_valid (const rcutils_allocator_t *allocator)
 Return true if the given allocator has non-null function pointers. More...
 
void * rcutils_reallocf (void *pointer, size_t size, rcutils_allocator_t *allocator)
 Emulate the behavior of reallocf. More...
 

Macro Definition Documentation

◆ RCUTILS_CHECK_ALLOCATOR

#define RCUTILS_CHECK_ALLOCATOR (   allocator,
  fail_statement 
)
Value:
if (!rcutils_allocator_is_valid(allocator)) { \
fail_statement; \
}
bool rcutils_allocator_is_valid(const rcutils_allocator_t *allocator)
Return true if the given allocator has non-null function pointers.

◆ RCUTILS_CHECK_ALLOCATOR_WITH_MSG

#define RCUTILS_CHECK_ALLOCATOR_WITH_MSG (   allocator,
  msg,
  fail_statement 
)
Value:
if (!rcutils_allocator_is_valid(allocator)) { \
RCUTILS_SET_ERROR_MSG(msg, rcutils_get_default_allocator()) \
fail_statement; \
}
bool rcutils_allocator_is_valid(const rcutils_allocator_t *allocator)
Return true if the given allocator has non-null function pointers.
rcutils_allocator_t rcutils_get_default_allocator(void)
Return a properly initialized rcutils_allocator_t with default values.

Typedef Documentation

◆ rcutils_allocator_t

Encapsulation of an allocator.

The default allocator uses malloc(), free(), calloc(), and realloc(). It can be obtained using rcutils_get_default_allocator().

The allocator should be trivially copyable. Meaning that the struct should continue to work after being assignment copied into a new struct. Specifically the object pointed to by the state pointer should remain valid until all uses of the allocator have been made. Particular care should be taken when giving an allocator to functions like rcutils_*_init() where it is stored within another object and used later. Developers should note that, while the fields of a const-qualified allocator struct cannot be modified, the state of the allocator can be modified.

Function Documentation

◆ rcutils_get_zero_initialized_allocator()

rcutils_allocator_t rcutils_get_zero_initialized_allocator ( void  )

Return a zero initialized allocator.

Note that this is an invalid allocator and should only be used as a placeholder.

◆ rcutils_get_default_allocator()

rcutils_allocator_t rcutils_get_default_allocator ( void  )

Return a properly initialized rcutils_allocator_t with default values.

This defaults to:

  • allocate = wraps malloc()
  • deallocate = wraps free()
  • reallocate = wraps realloc()
  • zero_allocate = wraps calloc()
  • state = NULL

Attribute Adherence —
Allocates Memory No
Thread-Safe Yes
Uses Atomics No
Lock-Free Yes

◆ rcutils_allocator_is_valid()

bool rcutils_allocator_is_valid ( const rcutils_allocator_t allocator)

Return true if the given allocator has non-null function pointers.

Will also return false if the allocator pointer is null.

◆ rcutils_reallocf()

void* rcutils_reallocf ( void *  pointer,
size_t  size,
rcutils_allocator_t allocator 
)

Emulate the behavior of reallocf.

This function will return NULL if the allocator is NULL or has NULL for function pointer fields.