Description
Allocates from a chosen memory node.
Ada already has a place to say where an object's memory comes from: the storage pool of its access type. This package supplies one whose subpools are memory nodes, so the node an object lives on is named at the point it is created:
Arena : Node_Pool (Policy => Flyology_NUMA.Placement.Bound,
Extent => 1024 * 1024);
type Sample_Access is access Sample
with Storage_Pool => Arena;
Item : constant Sample_Access :=
new (On_Node (Arena, Near)) Sample'(...);
The pool asks the host for whole pages and places each of them before handing any out, so an object allocated from a node's subpool comes from that node rather than merely being intended for it. How firmly depends on the policy: Bound draws only from the node, while Preferred lets the host draw from elsewhere when the node cannot satisfy the request.
Allocation succeeds whether or not placement did. A host that cannot place memory, and a host that refuses this process the placement it asked for, both still serve the allocation from wherever they choose; memory in the wrong place runs, and no memory does not. Placement_Reached reports which happened.
A pool is not task safe. Allocating from one subpool in two tasks at once can hand both the same address. Give each task its own pool, or serialize the allocations, or use this only where one task allocates.
Binding_Policy
subtype Binding_Policy is Placement.Policy_Kind range Placement.Preferred .. Placement.Interleaved;
The placement policies that draw memory from a named set of nodes.
A pool exists to put memory on a node, so the two policies that name no node are not among the ones it can be given. Asking for memory from wherever the host likes needs no pool of this kind.
Node_Pool
type Node_Pool
(Policy : Binding_Policy;
Extent : Byte_Count)
is new System.Storage_Pools.Subpools.Root_Storage_Pool_With_Subpools with private;
A storage pool whose subpools are memory nodes.
Memory is handed out by advancing through pages already obtained, and is returned to the host only when a subpool is deallocated or the pool goes out of scope. Freeing one object does nothing; this suits a body of memory built up and then discarded together, which is what a node-bound arena usually is.
Policy says how pages are drawn from the node a subpool stands for. Extent says how much memory to obtain at a time; a request larger than that obtains what it needs instead.
Allocation raises Storage_Error when the host will give the pool no more memory, and Program_Error when an allocation names no subpool.
On_Node
function On_Node (Pool : in out Node_Pool; Node : Node_Id) return Subpool_Handle
Return the subpool of Pool that draws memory from Node.
The subpool is made on first use and lives until Pool does. Asking again for the same node returns the same subpool.
Parameters
- Pool
The pool to take the subpool from.
- Node
The node the subpool should draw memory from.
Return value
The subpool for that node.
Placement_Reached
function Placement_Reached (Pool : Node_Pool; Node : Node_Id) return Boolean
Report whether the host accepted the placement of every page this node's subpool has obtained.
False means the host has no placement, or refused this process the placement it asked for, and the pages came from wherever the host chose. It does not mean allocation failed. False is also the answer before any page has been obtained, there being nothing placed yet.
True means the host accepted the request, which under Bound means the pages are on that node. Under Preferred the host was free to draw from elsewhere for pages the node could not satisfy.
Parameters
- Pool
The pool to inspect.
- Node
The node whose subpool to inspect.
Return value
True when the host accepted placement of every page obtained.
Reserved_Bytes
function Reserved_Bytes (Pool : Node_Pool; Node : Node_Id) return Byte_Count
Return the number of bytes Pool has obtained from the host for Node.
Parameters
- Pool
The pool to inspect.
- Node
The node whose subpool to inspect.
Return value
Bytes obtained, including any not yet handed out.
Subpool_Handle
subtype Subpool_Handle is System.Storage_Pools.Subpools.Subpool_Handle;
A reference to one of a pool's subpools, which for this pool is one of its memory nodes.