Section 16.8. Locality Group Hierarchy

16.8. Locality Group Hierarchy

The lgroup hierarchy is a directed acyclic graph that is similar to a tree, except that a node might have more than one parent. The root lgroup represents the whole machine. The root lgroup is the lgroup with the highest latency value in the system. Each of the child lgroups contains a subset of the hardware in the root lgroup. Each child lgroup is bounded by a lower latency value. Locality groups that are closer to the root have more resources and a higher latency. Locality groups that are closer to the leaves have fewer resources and a lower latency.

The following APIs enable the calling thread to navigate the lgroup hierarchy.

lgrp_cookie_stale(). The lgrp_cookie_stale(3LGRP) function determines whether the snapshot of the lgroup hierarchy represented by the given cookie is current.

lgrp_view(). The lgrp_view(3LGRP) function determines the view with which a given lgroup hierarchy snapshot was taken.

lgrp_nlgrps(). The lgrp_nlgrps(3LGRP) function returns the number of locality groups in the system. If a system has only one locality group, memory placement optimizations have no effect.

lgrp_root(). The lgrp_root(3LGRP) function returns the root lgroup ID.

lgrp_parents(). The lgrp_parents(3LGRP) function takes a cookie that represents a snapshot of the lgroup hierarchy and returns the number of parent lgroups for the specified lgroup.

lgrp_children(). The lgrp_children(3LGRP) function takes a cookie that represents the calling thread's snapshot of the lgroup hierarchy and returns the number of child lgroups for the specified lgroup.

lgrp_cpus(). The lgrp_cpus(3LGRP) function takes a cookie that represents a snapshot of the lgroup hierarchy and returns the number of CPUs in a given lgroup.

lgrp_mem_size(). The lgrp_mem_size(3LGRP) function takes a cookie that represents a snapshot of the lgroup hierarchy and returns the size of installed or free memory in the given lgroup. The lgrp_mem_size() function reports memory sizes in bytes.

16.8.1. Locality Group Characteristics

The following API retrieves information about the characteristics of a given lgroup.

lgrp_latency(). The lgrp_latency(3LGRP) function returns the latency between a CPU in one lgroup to the memory in another lgroup.

16.8.2. Locality Groups and Thread and Memory Placement

The locality group APIs used to discover and affect thread and memory placement with respect to lgroups are as follows:

lgrp_home(). The lgrp_home(3LGRP) function discovers thread placement.

meminfo(2). The meminfo(2) system call discovers memory placement.

madvise(3C). The MADV_ACCESS flags to the madvise(3C) function affect memory allocation among lgroups.

lgrp_affinity_set(3LGRP) The lgrp_affinity_set(3LGRP) function can affect thread and memory placement by setting a thread's affinity for a given lgroup.

In addition, the following applies:

• The affinities of an lgroup may specify an order of preference for lgroups from which to allocate resources.

• The kernel needs information about the likely pattern of an application's memory use in order to allocate memory resources efficiently.

• The madvise() function and its shared object analogue madv.so.1 provide this information to the kernel.

• A running process can gather memory usage information about itself by using the meminfo() system call.