Description
Reports the memory-node structure of the host.
Node and processor numbers are the host's own. They match sysfs paths, /proc/self/status, and numactl output, and they are sparse: a host with three nodes may number them 0, 2, and 5. Iterate a reported set rather than a numeric range.
Every query here is total. A host with no memory-node structure reports one node holding every processor, because a host whose memory is uniform genuinely has one memory domain. Placement is a separate question that this package does not answer.
A process may be permitted fewer nodes than the host has online. Reading the host's description does not establish permission, because a container sees the whole host description while a control group restricts what it may use. Allowed_Nodes reports the usable set and Online_Nodes reports the host's set.
Discovery runs once, while this package elaborates, and is kept for the life of the process. Nodes that appear or disappear afterwards are not observed. Discovery reads host description files and raises nothing: a host that answers nothing is reported as one node.
Allowed_Nodes
function Allowed_Nodes return Node_Set
Return the memory nodes this process may allocate on.
This is the set to act on. It is a subset of Online_Nodes and is smaller when a control group restricts the process.
Return value
The usable node set, never empty.
Byte_Count
type Byte_Count is range 0 .. 2**62 - 1;
A quantity of bytes.
Byte_Query
type Byte_Query (Available : Boolean := False) is record
case Available is
when True =>
Bytes : Byte_Count;
when False =>
null;
end case;
end record;
Result of a byte-quantity query the host may not answer.
Record fields
- Available
True when the host supplied a quantity.
- Bytes
The reported quantity in bytes.
Contains
function Contains (Set : Node_Set; Node : Node_Id) return Boolean
Report whether Node belongs to Set.
Parameters
- Set
The set to inspect.
- Node
The node to look for.
Return value
True when Node belongs to Set.
Contains
function Contains (Set : Processor_Set; Processor : Processor_Id) return Boolean
Report whether Processor belongs to Set.
Parameters
- Set
The set to inspect.
- Processor
The processor to look for.
Return value
True when Processor belongs to Set.
Count
function Count (Set : Node_Set) return Natural
Return the number of nodes in Set.
Parameters
- Set
The set to inspect.
Return value
The member count.
Count
function Count (Set : Processor_Set) return Natural
Return the number of processors in Set.
Parameters
- Set
The set to inspect.
Return value
The member count.
Discovery_Source
type Discovery_Source is (Host_Report, Single_Domain);
How the reported node structure was established.
Enumeration literals
- Host_Report
The host described its own memory nodes.
- Single_Domain
The host describes no memory-node structure, so one node holding every processor is reported.
Distance
type Distance is range 0 .. 255;
Relative access cost between two nodes, as declared by host firmware.
Ten names a node's distance to itself. The values order node pairs and are not latencies. Firmware declares them and often declares them poorly. A host that divides one processor package into several nodes reports small non-local values such as 11, so a value above ten does not mean a different package. Compare Package_Of for package identity.
Distance_Query
type Distance_Query (Available : Boolean := False) is record
case Available is
when True =>
Value : Distance;
when False =>
null;
end case;
end record;
Result of a distance query the host may not answer.
Record fields
- Available
True when the host supplied a distance.
- Value
The reported distance.
Element
function Element (Set : Node_Set; Position : Node_Cursor) return Node_Id
Return the node at Position.
Reading a position that Has_Element rejects is meaningless: a position past the last member raises Constraint_Error, and a position that is simply not a member reports itself.
Parameters
- Set
The set being iterated.
- Position
The position to read.
Return value
The member node. @exclude
Element
function Element (Set : Processor_Set; Position : Processor_Cursor) return Processor_Id
Return the processor at Position.
Parameters
- Set
The set being iterated.
- Position
The position to read.
Return value
The member processor. @exclude
First
function First (Set : Node_Set) return Node_Cursor
Return the first position in a node set iteration.
Parameters
- Set
The set being iterated.
Return value
The position of the lowest-numbered member. @exclude
First
function First (Set : Processor_Set) return Processor_Cursor
Return the first position in a processor set iteration.
Parameters
- Set
The set being iterated.
Return value
The position of the lowest-numbered member. @exclude
Has_Element
function Has_Element (Set : Node_Set; Position : Node_Cursor) return Boolean
Report whether a node set iteration has a member at Position.
Parameters
- Set
The set being iterated.
- Position
The position to test.
Return value
True while the iteration has a member. @exclude
Has_Element
function Has_Element (Set : Processor_Set; Position : Processor_Cursor) return Boolean
Report whether a processor set iteration has a member at Position.
Parameters
- Set
The set being iterated.
- Position
The position to test.
Return value
True while the iteration has a member. @exclude
Has_Memory
function Has_Memory (Node : Node_Id) return Boolean
Report whether Node carries memory.
Parameters
- Node
The node to test.
Return value
True when Node carries memory.
Has_Processors
function Has_Processors (Node : Node_Id) return Boolean
Report whether Node has any processor attached.
Parameters
- Node
The node to test.
Return value
True when at least one processor is attached to Node.
Is_Allowed
function Is_Allowed (Node : Node_Id) return Boolean
Report whether this process may allocate on Node.
Parameters
- Node
The node to test.
Return value
True when Node is available to this process.
Is_Online
function Is_Online (Node : Node_Id) return Boolean
Report whether the host lists Node as online.
Parameters
- Node
The node to test.
Return value
True when the host lists Node as online.
Max_Node
Max_Node : constant := 63;
Highest memory-node number this package represents.
Max_Processor
Max_Processor : constant := 4095;
Highest logical-processor number this package represents.
Memory_Bytes
function Memory_Bytes (Node : Node_Id) return Byte_Query
Return the memory Node carries.
Parameters
- Node
The node to inspect.
Return value
The node's memory in bytes, or No_Bytes.
Next
function Next (Set : Node_Set; Position : Node_Cursor) return Node_Cursor
Advance a node set iteration.
Parameters
- Set
The set being iterated.
- Position
The current position.
Return value
The position of the next member. @exclude
Next
function Next (Set : Processor_Set; Position : Processor_Cursor) return Processor_Cursor
Advance a processor set iteration.
Parameters
- Set
The set being iterated.
- Position
The current position.
Return value
The position of the next member. @exclude
No_Bytes
No_Bytes : constant Byte_Query := (Available => False);
A byte-quantity query with no host answer.
No_Distance
No_Distance : constant Distance_Query := (Available => False);
A distance query with no host answer.
No_Node
No_Node : constant Node_Query := (Available => False);
A node query with no host answer.
No_Value
No_Value : constant Value_Query := (Available => False);
A numeric query with no host answer.
Node_Count
function Node_Count return Positive
Return the number of memory nodes the host reports as online.
Return value
The online node count, at least one.
Node_Cursor
subtype Node_Cursor is Natural range 0 .. Max_Node + 1;
Position of a node within a node set iteration.
Node_Distance
function Node_Distance (From : Node_Id; To : Node_Id) return Distance_Query
Return the firmware-declared distance from one node to another.
Parameters
- From
The node being measured from.
- To
The node being measured to.
Return value
The declared distance, or No_Distance.
Node_Id
type Node_Id is range 0 .. Max_Node;
Memory-node number as reported by the host.
Node_Of
function Node_Of (Processor : Processor_Id) return Node_Query
Return the node Processor belongs to.
Parameters
- Processor
The processor to inspect.
Return value
The processor's node, or No_Node when the host does not say.
Node_Query
type Node_Query (Available : Boolean := False) is record
case Available is
when True =>
Node : Node_Id;
when False =>
null;
end case;
end record;
Result of a node query the host may not answer.
Record fields
- Available
True when the host supplied a node.
- Node
The reported memory node.
Node_Set
type Node_Set is private
with Iterable => (First => First, Next => Next, Has_Element => Has_Element, Element => Element);
A set of memory nodes.
Iterating a node set visits its members in increasing node order.
Online_Nodes
function Online_Nodes return Node_Set
Return the memory nodes the host reports as online.
Return value
The host's online node set, never empty.
Package_Of
function Package_Of (Node : Node_Id) return Value_Query
Return the processor package Node's processors sit on.
Two nodes sharing a package number are two memory domains of one processor package. This is the reliable way to tell that apart from two packages, because firmware-declared distances do not distinguish the cases consistently.
Parameters
- Node
The node to inspect.
Return value
The package number, or No_Value when the node has no processor attached or the host does not name the package of the one it has.
Processor_Cursor
subtype Processor_Cursor is Natural range 0 .. Max_Processor + 1;
Position of a processor within a processor set iteration.
Processor_Id
type Processor_Id is range 0 .. Max_Processor;
Logical-processor number as reported by the host, counting from zero.
Processor_Set
type Processor_Set is private
with Iterable => (First => First, Next => Next, Has_Element => Has_Element, Element => Element);
A set of logical processors.
Iterating a processor set visits its members in increasing processor order.
Processors_Of
function Processors_Of (Node : Node_Id) return Processor_Set
Return the processors attached to Node.
The set is empty for a node that carries memory but no processor, which a memory expander or a high-bandwidth memory tier produces.
Parameters
- Node
The node to inspect.
Return value
The node's processor set, possibly empty.
Support
function Support return Support_Report
Return what discovery established about this host.
Return value
The discovery outcome.
Support_Report
type Support_Report is record
Source : Discovery_Source;
Restricted : Boolean;
Complete : Boolean;
Consecutive_Processors : Boolean;
end record;
What discovery established about this host and this process.
Record fields
- Source
How the node structure was established.
- Restricted
True when this process may use fewer nodes than the host has online, which a control-group memory-node restriction causes.
- Complete
True when the host's whole description was read and represented. A false value means some part of it was not: numbers above Max_Node or Max_Processor, a list naming more ranges than this package holds, or a description this package could not parse. The reported sets are then partial rather than wrong.
- Consecutive_Processors
True when the host numbers its processors consecutively from zero. To_CPU answers only then.
To_CPU
function To_CPU (Processor : Processor_Id) return System.Multiprocessors.CPU_Range
Return the Ada processor number that names Processor.
Ada numbers processors from one and the host numbers them from zero, so the mapping is Processor + 1. GNAT applies that arithmetic without checking it, which is correct only while the host numbers its processors consecutively from zero. A host with an offline processor breaks that, and the arithmetic then names a processor the caller did not intend.
This function returns Not_A_Specific_CPU when discovery saw processor numbering that the mapping cannot carry, so that a caller pinning a task can tell the difference instead of pinning to the wrong place.
Parameters
- Processor
The host processor number to convert.
Return value
The Ada processor number, or Not_A_Specific_CPU.
Value_Or
function Value_Or (Result : Byte_Query; Fallback : Byte_Count) return Byte_Count
Explicitly choose a fallback for an unanswered byte query.
Parameters
- Result
The query result to inspect.
- Fallback
The quantity to return when Result is unanswered.
Return value
Result.Bytes when available, otherwise Fallback.
Value_Or
function Value_Or (Result : Distance_Query; Fallback : Distance) return Distance
Explicitly choose a fallback for an unanswered distance query.
Parameters
- Result
The query result to inspect.
- Fallback
The distance to return when Result is unanswered.
Return value
Result.Value when available, otherwise Fallback.
Value_Or
function Value_Or (Result : Value_Query; Fallback : Natural) return Natural
Explicitly choose a fallback for an unanswered numeric query.
Parameters
- Result
The query result to inspect.
- Fallback
The value to return when Result is unanswered.
Return value
Result.Value when available, otherwise Fallback.
Value_Query
type Value_Query (Available : Boolean := False) is record
case Available is
when True =>
Value : Natural;
when False =>
null;
end case;
end record;
Result of a plain numeric query the host may not answer.
Record fields
- Available
True when the host supplied a value.
- Value
The reported value.