### Navigation

- index
- next |
- previous |
- Memory Pool System 1.111.0 documentation »
- Reference »

# 4. Pools

Within an arena a client program creates one or more pools. A pool is responsible for requesting memory from the arena and making it available for allocation.

`mps_pool_t`

  The type of pools.

  A pool is responsible for requesting memory from the arena and making it available to the client program via `mps_alloc()` or via an allocation point.

mps_res_t `mps_pool_create`(mps_pool_t *pool_o, mps_arena_t arena, mps_class_t class, ...)

  Create a pool in an arena.

  `pool_o` points to a location that will hold a pointer to the new pool.

  `arena` is the arena in which to create the pool.

  `class` is the pool class of the new pool.

  Some pool classes require additional arguments to be passed to `mps_pool_create()`. See the documentation for the pool class.

  Returns `MPS_RES_OK` if the pool is created successfully, or another result code otherwise.

  The pool persists until it is destroyed by calling `mps_pool_destroy()`.

  Note

  There’s an alternative function `pool_create_v()` that takes its extra arguments using the standard C `va_list` mechanism.

mps_res_t `mps_pool_create_v`(mps_pool_t *pool_o, mps_arena_t arena, mps_class_t class, va_list args)

  An alternative to `mps_pool_create()` that takes its extra arguments using the standard C `va_list` mechanism.

void `mps_pool_destroy`(mps_pool_t pool)

  Destroy a pool.

  `pool` is the pool to destroy.

  This function checks the consistency of the pool, destroys the pool’s internal control structures and causes the pool’s memory to be returned to the arena for reuse by other pools, or to be returned to the operating system. Blocks allocated from the pool may no longer be used.

  It is an error to destroy a pool without first destroying all allocation points and segregated allocation caches created in the pool.

## 4.1. Pool classes

Pools belong to pool classes that specify policies for how their memory is managed. Some pools are manually managed (you must call `mps_free()` to return a block of memory to the pool) and others are automatically managed (the garbage collector reclaims unreachable blocks).

See the Pool reference for a list of pool classes.

`mps_class_t`

  The type of pool classes.

  Note

  This should really have been called `mps_pool_class_t` but it is too late to change it now.

## 4.2. Pool introspection

mps_bool_t `mps_addr_pool`(mps_pool_t *pool_o, mps_arena_t arena, mps_addr_t addr)

  Determine the pool to which an address belongs.

  `pool_o` points to a location that will hold the address of the pool, if one is found.

  `arena` is the arena whose pools will be considered.

  `addr` is the address.

  If `addr` is the address of a location inside a block allocated from a pool in `arena`, then update the location pointed to by `pool_o` with the address of the pool, and return true.

  If `addr` points to a location that is not managed by `arena`, return false.

  If neither of the above conditions is satisfied, `mps_addr_pool()` may return either true or false.

  Note

  This function might return a false positive by returning true if you ask about an address that happens to be inside memory managed by a pool, but which is not inside a block allocated by that pool. It never returns a false negative.

  The result from this function is valid only at the instant at which the function returned. In some circumstances the result may immediately become invalidated. For reliable results call this function and interpret the result while the arena is in the parked state.

### Navigation

- index
- next |
- previous |
- Memory Pool System 1.111.0 documentation »
- Reference »