lwpa_mempool

Overview

Memory pools with fixed-size elements.

#include "lwpa_mempool.h"

This module can be used to declare memory pools containing some number of objects of an arbitrary type. Only objects of that type can be allocated from the pool or freed back into it. Allocations and deallocations are ensured to be thread_safe by an lwpa_mutex internally.

Data Structures
struct	LwpaMempool
struct	LwpaMempoolDesc
	(Not for direct usage) A memory pool description structure. More...

Macros
#define	LWPA_MEMPOOL_DECLARE(name)   extern LwpaMempoolDesc name##_pool_desc;
	Declare a pool as an external variable. More...
#define	LWPA_MEMPOOL_DEFINE(name, type, size)
	Define a new memory pool. More...
#define	lwpa_mempool_init(name)   lwpa_mempool_init_priv(&name##_pool_desc)
	Initialize a memory pool. More...
#define	lwpa_mempool_alloc(name)   lwpa_mempool_alloc_priv(&name##_pool_desc)
	Allocate a new element from a memory pool. More...
#define	lwpa_mempool_free(name, mem)   lwpa_mempool_free_priv(&name##_pool_desc, mem)
	Free an element back to a memory pool. More...
#define	lwpa_mempool_size(name)   (name##_pool_desc.pool_size)
	Get the total size of a memory pool. More...
#define	lwpa_mempool_used(name)   lwpa_mempool_used_priv(&name##_pool_desc)
	Get the number of elements currently allocated from a memory pool. More...

Typedefs
typedef struct LwpaMempool	LwpaMempool
	(Not for direct usage) A tiny structure simply used to maintain the freelist for each pool.
typedef struct LwpaMempoolDesc	LwpaMempoolDesc
	(Not for direct usage) A memory pool description structure. More...

Functions
lwpa_error_t	lwpa_mempool_init_priv (LwpaMempoolDesc *desc)
void *	lwpa_mempool_alloc_priv (LwpaMempoolDesc *desc)
void	lwpa_mempool_free_priv (LwpaMempoolDesc *desc, void *elem)
size_t	lwpa_mempool_used_priv (LwpaMempoolDesc *desc)

Macro Definition Documentation

lwpa_mempool_alloc

#define lwpa_mempool_alloc

(

name

)

lwpa_mempool_alloc_priv(&name##_pool_desc)

Allocate a new element from a memory pool.

Parameters

name	The name of the memory pool from which to allocate a new element.

Returns

Pointer to the newly-allocated element (success) or NULL (pool is out of memory).

LWPA_MEMPOOL_DECLARE

#define LWPA_MEMPOOL_DECLARE

(

name

)

extern LwpaMempoolDesc name##_pool_desc;

Declare a pool as an external variable.

This optional macro is useful for header files; when used, it must be paired with a call of LWPA_MEMPOOL_DEFINE() using the same name.

Parameters

name	The name of the memory pool.

LWPA_MEMPOOL_DEFINE

#define LWPA_MEMPOOL_DEFINE	(		name,
			type,
			size
	)

Value:

  type name##_pool[size];                                                         \
  struct LwpaMempool name##_pool_list[size];                                      \
  struct LwpaMempoolDesc name##_pool_desc = {sizeof(type),     /* elem_size */    \
                                             size,             /* pool_size */    \
                                             NULL,             /* freelist */     \
                                             name##_pool_list, /* list */         \
                                             0,                /* current_used */ \
                                             name##_pool /* pool */}

Define a new memory pool.

Expands to a number of variable definitions. Should not be used in a header file; if you want your memory pool to be accessible from multiple source files, use LWPA_MEMPOOL_DECLARE() in the header file in addition to this macro.

Parameters

name	The name of the memory pool.
type	The type of each element in the memory pool (i.e. int, struct foo)
size	The number of elements in the memory pool.

lwpa_mempool_free

#define lwpa_mempool_free	(		name,
			mem
	)		lwpa_mempool_free_priv(&name##_pool_desc, mem)

Free an element back to a memory pool.

CAUTION: Freeing a pointer to an element that has not previously been allocated or a pointer to somewhere outside of the memory pool will cause undefined behavior.

Parameters

name	The name of the memory pool to which to free an element.
mem	Pointer to the element to free.

lwpa_mempool_init

#define lwpa_mempool_init

(

name

)

lwpa_mempool_init_priv(&name##_pool_desc)

Initialize a memory pool.

This macro must be called on a pool before using lwpa_mempool_alloc() or lwpa_mempool_free() on it. There is no deinitialization function because there is no cleanup necessary; to reset a pool, simply call this function again.

Parameters

name	The name of the memory pool to initialize.

Returns

LWPA_OK: The memory pool was initialized successfully.
LWPA_SYSERR: An internal system call error occurred.

lwpa_mempool_size

#define lwpa_mempool_size

(

name

)

(name##_pool_desc.pool_size)

Get the total size of a memory pool.

This is a constant value that was provided in the LWPA_MEMPOOL_DEFINE() call.

Parameters

name	The name of the memory pool of which to get the size.

Returns

The size of the memory pool.

lwpa_mempool_used

#define lwpa_mempool_used

(

name

)

lwpa_mempool_used_priv(&name##_pool_desc)

Get the number of elements currently allocated from a memory pool.

Parameters

name	The name of the memory pool for which to get the current usage.

Returns

The number of elements currently allocated.

Typedef Documentation

LwpaMempoolDesc

typedef struct LwpaMempoolDesc LwpaMempoolDesc

(Not for direct usage) A memory pool description structure.

Do not declare or use this structure directly; instead, use LWPA_MEMPOOL_DECLARE(), LWPA_MEMPOOL_DEFINE() and the lwpa_mempool_* macros to interact with it.