[#PoolResource]
= PoolResource
:mrdocs:

A memory resource similar to std::pmr::unsynchronized_pool_resource, but optimized for node‐based containers. It has the following properties:

== Synopsis

Declared in `<support/allocators/pool.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<
    std::size_t MAX_BLOCK_SIZE_BYTES,
    std::size_t ALIGN_BYTES>
class PoolResource final
----

== Description

* Owns the allocated memory and frees it on destruction, even when deallocate has not been called on the allocated blocks.

* Consists of a number of pools, each one for a different block size. Each pool holds blocks of uniform size in a freelist.

* Exhausting memory in a freelist causes a new allocation of a fixed size chunk. This chunk is used to carve out blocks.

* Block sizes or alignments that can not be served by the pools are allocated and deallocated by operator new().

PoolResource is not thread‐safe. It is intended to be used by PoolAllocator.

An example: If you create a PoolResource<128, 8>(262144) and perform a bunch of allocations and deallocate 2 blocks with size 8 bytes, and 3 blocks with size 16, the members will look like this:

m_free_lists m_allocated_chunks ┌───┐ ┌───┐ ┌────────────‐‐‐‐‐‐‐──────┐ │ │ blocks │ ├─►│ 262144 B │ │ │ ┌─────┐ ┌─────┐ └─┬─┘ └────────────‐‐‐‐‐‐‐──────┘ │ 1 ├─►│ 8 B ├─►│ 8 B │ │ │ │ └─────┘ └─────┘ : │ │ │ │ │ ┌─────┐ ┌─────┐ ┌─────┐ ▼ │ 2 ├─►│16 B ├─►│16 B ├─►│16 B │ ┌───┐ ┌─────────────────────────┐ │ │ └─────┘ └─────┘ └─────┘ │ ├─►│ ▲ │ ▲ │ │ └───┘ └──────────┬──────────────┘ │ │ . │ │ m_available_memory_end │ . │ m_available_memory_it │ . │ │ │ │ │ │16 │ └───┘

Here m_free_lists[1]holds the 2 blocks of size 8 bytes, and m_free_lists[2] holds the 3 blocks of size 16. The blocks came from the data stored in the m_allocated_chunks list. Each chunk has bytes 262144. The last chunk has still some memory available for the blocks, and when m_available_memory_it is at the end, a new chunk will be allocated and added to the list.

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:PoolResource/2constructor-01.adoc[`PoolResource`]         [.small]#[constructor]#
| Constructors
| xref:PoolResource/2destructor.adoc[`~PoolResource`] [.small]#[destructor]#
| Deallocates all memory allocated associated with the memory resource.
| xref:PoolResource/operator_assign-05c.adoc[`operator=`] 
| Assignment operators
| xref:PoolResource/Allocate.adoc[`Allocate`] 
| Allocates a block of bytes. If possible the freelist is used, otherwise allocation is forwarded to ::operator new().
| xref:PoolResource/ChunkSizeBytes.adoc[`ChunkSizeBytes`] 
| Size in bytes to allocate per chunk, currently hardcoded to a fixed size.
| xref:PoolResource/Deallocate.adoc[`Deallocate`] 
| Returns a block to the freelists, or deletes the block when it did not come from the chunks.
| xref:PoolResource/NumAllocatedChunks.adoc[`NumAllocatedChunks`] 
| Number of allocated chunks
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:PoolResourceTester.adoc[PoolResourceTester]`
| Access to internals for testing purpose only
|===

== Template Parameters

[cols="1,4"]
|===
| Name| Description
| *MAX_BLOCK_SIZE_BYTES*
| Maximum size to allocate with the pool. If larger sizes are requested, allocation falls back to new().
| *ALIGN_BYTES*
| Required alignment for the allocations.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#