Description
Places memory on chosen nodes.
The parent package reports what the host has. This package acts on it. The two are separate because reading a description always succeeds and acting on one often does not: a host may have no placement interface at all, and a process may be refused the one its host has.
Support reports which of those applies before anything is attempted, and every operation reports its own outcome. Nothing here raises.
Placement governs where pages come from. It does not move a running thread; a thread is placed with the CPU aspect or a dispatching domain, using the processors the parent package reports for a node.
Apply_To
procedure Apply_To
(Base : System.Address;
Length : Byte_Count;
Policy : Policy_Kind;
Nodes : Node_Set;
Move : Boolean := False;
Result : out Placement_Outcome)
Place the pages of a memory range on Nodes.
This governs pages the range acquires from now on. Pages it already holds stay where they are unless Move is requested.
Move is a request, not a guarantee. Pages shared with another process are left alone, and Applied reports that the host accepted the policy rather than that every page moved. Node_Of_Address reports where a particular page actually ended up.
Base must begin on a Page_Size boundary; the range extends to the page boundary at or beyond Base + Length.
Parameters
- Base
First byte of the range, on a page boundary.
- Length
Number of bytes in the range.
- Policy
How pages should be drawn from Nodes.
- Nodes
The nodes to draw from. Ignored for Local and Unrestricted.
- Move
Whether to move the pages the range already holds.
- Result
What became of the request.
Apply_To_Thread
procedure Apply_To_Thread (Policy : Policy_Kind; Nodes : Node_Set; Result : out Placement_Outcome)
Place the memory this thread acquires from now on.
This governs later allocations by the calling thread, whatever their source. It does not move memory the thread already holds, and a thread created afterwards inherits it.
Parameters
- Policy
How pages should be drawn from Nodes.
- Nodes
The nodes to draw from. Ignored for Local and Unrestricted.
- Result
What became of the request.
Node_Of_Address
function Node_Of_Address (Location : System.Address) return Node_Query
Report which node holds the page containing an address.
Asking this of a page the process has not yet touched causes it to be acquired, because the host answers by placing the page. Ask only about memory already written to.
Parameters
- Location
An address within the page to ask about.
Return value
The node holding that page, or No_Node.
Page_Size
function Page_Size return Byte_Count
Return the page size that placement acts in units of.
A range passed to Apply_To must begin on a multiple of this, and is placed up to the page boundary at or beyond its end.
Return value
The host page size in bytes.
Permitted_Nodes
function Permitted_Nodes return Node_Set
Report the nodes this process may place memory on, as the host says now rather than as it said when the parent package was elaborated.
This differs from Allowed_Nodes when the process was moved between control groups after it started.
Return value
The permitted node set, empty when the host does not say.
Placement_Outcome
type Placement_Outcome is
(Applied, Not_Supported, Not_Permitted, Unusable_Nodes, Unaligned, Insufficient_Memory, Failed);
What became of a placement request.
Enumeration literals
- Applied
The host accepted the request.
- Not_Supported
This host has no memory-placement interface.
- Not_Permitted
This process may not place memory, or may not place it on the nodes it asked for.
- Unusable_Nodes
The node set is empty, or names a node the host does not have online, when the policy needs one.
- Unaligned
The range does not begin on a page boundary. Placement acts on whole pages, so a range that begins inside one cannot be placed. Page_Size reports the boundary to use.
- Insufficient_Memory
The host could not satisfy the request.
- Failed
The host refused the request for another reason.
Policy_Kind
type Policy_Kind is (Preferred, Bound, Interleaved, Local, Unrestricted);
How pages should be drawn from a set of nodes.
Enumeration literals
- Preferred
Draw from the lowest-numbered node in the set, and from elsewhere rather than fail when it cannot satisfy the request. The host's interface takes one node here, so any further node in the set contributes nothing. Use Bound or Interleaved to name several.
- Bound
Draw only from the set. A request the set cannot satisfy fails rather than drawing from elsewhere, which can mean running out of memory while other nodes still have some.
- Interleaved
Draw from the set in rotation, one page at a time. This trades the latency of a nearby node for the combined transfer rate of several, which suits memory read by every node at once.
- Local
Draw from the node of whichever processor first touches each page. The node set is not used.
- Unrestricted
Remove any policy and return to the host default. The node set is not used.
Support
function Support return Support_Level
Report whether this process can place memory.
Return value
What this process may do on this host.
Support_Level
type Support_Level is (Supported, Unsupported_Host, Denied);
Whether this process can place memory on this host.
Enumeration literals
- Supported
The host provides placement and this process may use it.
- Unsupported_Host
The host has no memory-placement interface. macOS is such a host, and so is a Linux host built without memory-node support or running an architecture this package does not know the placement calls for.
- Denied
The host provides placement and this process is not permitted to use it. A container sandbox commonly causes this: the machine underneath has memory nodes, and the process may not act on them. It is not the same as a host without the facility.