Memory Pool
Eina » Tools

This group discusses the functions that provide memory pool management. More...

## Typedefs

typedef struct _Eina_Mempool | Eina_Mempool
| The opaque type for the mempool structure.
typedef struct _Eina_Mempool_Backend | Eina_Mempool_Backend
| The opaque type for the mempool backend type.
typedef void(* | Eina_Mempool_Repack_Cb) (void *dst, void *src, void *data)
| The callback type which is called when the mempool "repacks" its data.

## Functions

EINA_API Eina_Mempool * | eina_mempool_add (const char *name, const char *context, const char *options,...)
| Creates a new mempool of the given type.
EINA_API void | eina_mempool_del (Eina_Mempool *mp)
| Deletes the given mempool.
static void * | eina_mempool_realloc (Eina_Mempool *mp, void *element, unsigned int size)
| Re-allocates an amount memory by the given mempool.
static void * | eina_mempool_malloc (Eina_Mempool *mp, unsigned int size)
| Allocates memory using the given mempool.
static void * | eina_mempool_malloc_near (Eina_Mempool *mp, void *after, void *before, unsigned int size)
| Allocates memory in the given mempool using locality hint to improve future memory access use.
static void * | eina_mempool_calloc (Eina_Mempool *mp, unsigned int size)
| Allocates and zeros memory using the given mempool.
static void | eina_mempool_free (Eina_Mempool *mp, void *element)
| Frees resources previously allocated by the given mempool.
EINA_API void | eina_mempool_repack (Eina_Mempool *mp, Eina_Mempool_Repack_Cb cb, void *data)
| Repacks the objects in the mempool.
EINA_API void | eina_mempool_gc (Eina_Mempool *mp)
| Runs a garbage collection cycle.
static Eina_Bool | eina_mempool_from (Eina_Mempool *mp, void *element)
| Check if a pointer is a valid element from the mempool.
EINA_API void | eina_mempool_statistics (Eina_Mempool *mp)
| Has the backend update its internal statistics.
static Eina_Iterator * | eina_mempool_iterator_new (Eina_Mempool *mp)
| Provide an iterator to walk all allocated elements from a specified mempool.
EINA_API Eina_Bool | eina_mempool_register (Eina_Mempool_Backend *be)
| Registers the given memory pool backend.
EINA_API void | eina_mempool_unregister (Eina_Mempool_Backend *be)
| Unregisters the given memory pool backend.
static unsigned int | eina_mempool_alignof (unsigned int size)
| Computes the alignment that would be used when allocating a object of size `size`.

## Variables

EINA_API Eina_Error | EINA_ERROR_NOT_MEMPOOL_MODULE

## Detailed Description

This group discusses the functions that provide memory pool management.

Several mempools are available:

- `chained_pool:` It is the default one. It allocates a big chunk of memory with malloc() and splits the result into chunks of the requested size that are pushed inside a stack. When requested, it takes this pointer from the stack to give them to whoever wants them.
- `pass_through:` it just call malloc() and free(). It may be faster on some computers than using our own allocators (like having a huge L2 cache, over 4MB).
- `one_big:` It calls malloc() just one time for the requested number of items. This is useful when you know in advance how many objects of some type live during the life of the mempool.

## Typedef Documentation

## Eina_Mempool_Repack_Cb

typedef void(* Eina_Mempool_Repack_Cb) (void *dst, void *src, void *data)

The callback type which is called when the mempool "repacks" its data.

I.e. moves it around to optimize the way it is stored in memory. This is useful to improve data locality and to free internal pools back to the OS.

Note
  The callback needs to update users of the data to stop accessing the object from the old location and access it using the new location instead. The copy of memory is taken care of by the mempool.

## Function Documentation

## eina_mempool_add()

EINA_API Eina_Mempool * eina_mempool_add | ( | const char * | name,
|  | const char * | context,
|  | const char * | options,
|  |  | ... )

Creates a new mempool of the given type.

Parameters

  [in] | name | Name of the mempool kind to use.
  [in] | context | Identifier of the mempool created (for debug purposes).
  [in] | options | Unused. Use the variable arguments list instead to pass options to the mempool.
  [in] | ... | Additional options to pass to the allocator; depends entirely on the type of mempool ("int pool size" for chained and "int item_size" for one_big.

Returns
  Newly allocated mempool instance, NULL otherwise.

References DBG, and EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by edje_init(), and eina_cow_add().

## eina_mempool_del()

EINA_API void eina_mempool_del | ( | Eina_Mempool * | mp | ) |

Deletes the given mempool.

Parameters

  [in] | mp | The mempool to delete

References DBG, EINA_API, and EINA_SAFETY_ON_NULL_RETURN.

Referenced by edje_init(), and eina_cow_del().

## eina_mempool_realloc()

void * eina_mempool_realloc | ( | Eina_Mempool * | mp,
|  | void * | element,
|  | unsigned int | size )

inline static

Re-allocates an amount memory by the given mempool.

Parameters

  [in] | mp | The mempool
  [in] | element | The element to re-allocate
  [in] | size | The size in bytes to re-allocate

Returns
  The newly re-allocated data

Note
  This function re-allocates and returns `element` with `size` bytes using the mempool `mp`. If not used anymore, the data must be freed with eina_mempool_free().

Warning
  No checks are done for `mp`.

See also
  eina_mempool_free()

References EINA_ARG_NONNULL, and EINA_WARN_UNUSED_RESULT.

## eina_mempool_malloc()

void * eina_mempool_malloc | ( | Eina_Mempool * | mp,
|  | unsigned int | size )

inline static

Allocates memory using the given mempool.

Parameters

  [in] | mp | The mempool
  [in] | size | The size in bytes to allocate

Returns
  The newly allocated data

Note
  This function allocates and returns `size` bytes using the mempool `mp`. If not used anymore, the data must be freed with eina_mempool_free().

Warning
  No checks are done for `mp`.

See also
  eina_mempool_free()

References EINA_ARG_NONNULL, EINA_MALLOC, and EINA_WARN_UNUSED_RESULT.

## eina_mempool_malloc_near()

void * eina_mempool_malloc_near | ( | Eina_Mempool * | mp,
|  | void * | after,
|  | void * | before,
|  | unsigned int | size )

inline static

Allocates memory in the given mempool using locality hint to improve future memory access use.

Parameters

  [in] | mp | The mempool
  [in] | after | Hint to the nearest pointer after which to try find an empty spot.
  [in] | before | Hint to the nearest pointer before which to try find an empty spot.
  [in] | size | The size in bytes to allocate

Returns
  The newly allocated data that might be near `after` and `before`.

This function is to be used to improve cache locality of structure that are likely to be used one after another. An example of this use would be Eina_List.

Note
  This function allocates and returns `size` bytes using the mempool `mp`. If not used anymore, the data must be freed with eina_mempool_free().
  `after` and `before` must be either `NULL` or allocated by the same mempool `mp`. They are hint and if no space near them is found, memory will be allocated without locality improvement.

Warning
  No checks are done for `mp`.

See also
  eina_mempool_free()

References EINA_WARN_UNUSED_RESULT.

## eina_mempool_calloc()

void * eina_mempool_calloc | ( | Eina_Mempool * | mp,
|  | unsigned int | size )

inline static

Allocates and zeros memory using the given mempool.

Parameters

  [in] | mp | The mempool
  [in] | size | The size in bytes to allocate

Returns
  The newly allocated data

This function allocates, zeroes, and returns `size` bytes using the mempool `mp`. If not used anymore, the data must be freed with eina_mempool_free().

Warning
  No checks are done for `mp`.

Since
  1.2

See also
  eina_mempool_free()

References EINA_ARG_NONNULL, EINA_MALLOC, and EINA_WARN_UNUSED_RESULT.

## eina_mempool_free()

void eina_mempool_free | ( | Eina_Mempool * | mp,
|  | void * | element )

inline static

Frees resources previously allocated by the given mempool.

Parameters

  [in] | mp | The mempool
  [in] | element | The data to free

This function frees `element` allocated by `mp`. `element` must have been obtained from eina_mempool_malloc(), eina_mempool_calloc(), or eina_mempool_realloc().

Warning
  No checks are done for `mp`.

See also
  eina_mempool_malloc()
  eina_mempool_calloc()
  eina_mempool_realloc()

References EINA_API, EINA_ARG_NONNULL, eina_mempool_gc(), and eina_mempool_repack().

## eina_mempool_repack()

EINA_API void eina_mempool_repack | ( | Eina_Mempool * | mp,
|  | Eina_Mempool_Repack_Cb | cb,
|  | void * | data )

Repacks the objects in the mempool.

Parameters

  [in] | mp | The mempool
  [in] | cb | A callback to update the pointers the objects with their new location
  [in] | data | Data to pass as third argument to `cb`

See also
  Eina_Mempool_Repack_Cb
  _Eina_Mempool_Backend

References DBG, EINA_API, and EINA_SAFETY_ON_NULL_RETURN.

Referenced by eina_mempool_free().

## eina_mempool_gc()

EINA_API void eina_mempool_gc | ( | Eina_Mempool * | mp | ) |

Runs a garbage collection cycle.

Parameters

  [in] | mp | The mempool

References DBG, EINA_API, and EINA_SAFETY_ON_NULL_RETURN.

Referenced by eina_mempool_free().

## eina_mempool_from()

Eina_Bool eina_mempool_from | ( | Eina_Mempool * | mp,
|  | void * | element )

inline static

Check if a pointer is a valid element from the mempool.

Parameters

  [in] | mp | The mempool
  [in] | element | The data to free

Returns
  EINA_TRUE if the element is a valid element of the mempool, EINA_FALSE otherwise

Since
  1.20

References EINA_API, EINA_ARG_NONNULL, and eina_mempool_statistics().

## eina_mempool_statistics()

EINA_API void eina_mempool_statistics | ( | Eina_Mempool * | mp | ) |

Has the backend update its internal statistics.

Parameters

  [in] | mp | The mempool

References DBG, EINA_API, and EINA_SAFETY_ON_NULL_RETURN.

Referenced by eina_mempool_from().

## eina_mempool_iterator_new()

Eina_Iterator * eina_mempool_iterator_new | ( | Eina_Mempool * | mp | ) |

inline static

Provide an iterator to walk all allocated elements from a specified mempool.

Parameters

  [in] | mp | The mempool

Returns
  `NULL` if it is not possible to iterate over the mempool, a valid iterator otherwise.

Note
  This call is expected to be slow and should not be used in any performance critical area.

Since
  1.23

References EINA_API, EINA_ARG_NONNULL, eina_mempool_alignof(), eina_mempool_register(), and eina_mempool_unregister().

## eina_mempool_register()

EINA_API Eina_Bool eina_mempool_register | ( | Eina_Mempool_Backend * | be | ) |

Registers the given memory pool backend.

Parameters

  [in] | be | The backend

Returns
  EINA_TRUE if backend has been correctly registered, EINA_FALSE otherwise.

References DBG, eina_hash_add(), EINA_SAFETY_ON_NULL_RETURN_VAL, and _Eina_Mempool_Backend::name.

Referenced by eina_mempool_iterator_new().

## eina_mempool_unregister()

EINA_API void eina_mempool_unregister | ( | Eina_Mempool_Backend * | be | ) |

Unregisters the given memory pool backend.

Parameters

  [in] | be | The backend

References DBG, eina_hash_del(), EINA_SAFETY_ON_NULL_RETURN, and _Eina_Mempool_Backend::name.

Referenced by eina_mempool_iterator_new().

## eina_mempool_alignof()

unsigned int eina_mempool_alignof | ( | unsigned int | size | ) |

inline static

Computes the alignment that would be used when allocating a object of size `size`.

Parameters

  [in] | size |

Returns
  The alignment for an allocation of size `size`.

References EINA_UNLIKELY.

Referenced by eina_cow_add(), and eina_mempool_iterator_new().