5. 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.
-
type 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_k(mps_pool_t *pool_o, mps_arena_t arena, mps_pool_class_t pool_class, mps_arg_s args[])¶
-
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.pool_class
is the pool class of the new pool.args
are keyword arguments specific to the pool class. 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()
.
-
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.
Warning
It is not safe to carry on running the garbage collector after destroying an automatically managed pool that contains any objects that are reachable from your roots, or any objects that have been registered for finalization but not yet finalized.
Our recommended approach is to destroy automatically managed pools just before destroying the arena, and then only while the arena is in the parked state. Thus a safe tear-down sequence looks like this:
mps_arena_park(arena); /* destroy threads and roots belonging to the arena */ /* destroy allocation points and caches belonging to the pool */ mps_pool_destroy(pool); /* destroy chains and formats belonging to the arena */ mps_arena_destroy(arena);
5.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.
-
type mps_pool_class_t¶
The type of pool classes.
5.2. Pool introspection¶
-
size_t mps_pool_total_size(mps_pool_t pool)¶
Return the total memory allocated from the arena and managed by the pool.
pool
is the pool.The result includes memory in use by the client program, memory that’s available for use by the client program, and memory that’s lost to fragmentation. It does not include memory used by the pool’s internal control structures.
-
size_t mps_pool_free_size(mps_pool_t pool)¶
Return the free memory: memory managed by the pool but not in use by the client program.
pool
is the pool.The result includes memory that’s available for use by the client program, and memory that’s lost to fragmentation. It does not include memory used by the pool’s internal control structures.
-
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 inarena
, then update the location pointed to bypool_o
with the address of the pool, and return true.If
addr
points to a location that is not managed byarena
, 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.
See also
To find out which object format describes the object at the address, use
mps_addr_fmt()
. If you only care whether the address belongs to a particular arena, usemps_arena_has_addr()
.
-
mps_res_t mps_pool_walk(mps_pool_t pool, mps_area_scan_t scan_area, void *closure)¶
Visit all formatted objects in a pool. The pool must be automatically managed. The pool’s arena must be in the parked state.
pool
is the pool whose formatted objects are visited.scan_area
is an area scanning function. See Area scanners.closure
is an arbitrary pointer that will be passed toscan_area
.The scanning function is called multiple times with disjoint areas of memory that cover all formatted objects in the pool. The areas may also include padding objects if the pool’s format has a padding method, but never includes forwarding objects since the arena is in the parked state.
The scanning function must follow the Scanning protocol. In particular, it must fix every reference in the area. The scanning function may return
MPS_RES_OK
to continue visiting areas of formatted objects, or return other Result codes to stop visiting and return to the caller.Note
If the scanning function modifies a reference, it must scan the modified reference. It is safe to scan the original reference as well, but this may lead to unwanted retention.