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"
Include dependency graph for allocator.h:
This graph shows which files directly or indirectly include this file:

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; \
}

◆ 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); \
fail_statement; \
}

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.

Parameters
[in]allocatorto be checked by the function

◆ 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.

Parameters
[in,out]pointerto the memory which will be reallocated
[in]sizein bytes
[in]allocatorto be used to allocate and deallocate memory
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.