Locality Group Hierarchy

The APIs that are described in this section enable the calling thread to
navigate the lgroup 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 and contains all
of that machine's resources. 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 that is 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. An lgroup can
contain resources directly within its latency boundary. An lgroup can also contain leaf
lgroups that contain their own sets of resources. The resources of leaf lgroups
are available to the lgroup that encapsulates those leaf lgroups.

Using lgrp_cookie_stale()

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

The cookie returned by the lgrp_init() function can become stale due to several
reasons that depend on the view that the snapshot represents. A cookie that
is returned by calling the lgrp_init() function with the view set to LGRP_VIEW_OS
can become stale due to changes in the lgroup hierarchy such as dynamic
reconfiguration or a change in a CPU's online status. A cookie that is
returned by calling the lgrp_init() function with the view set to LGRP_VIEW_CALLER
can become stale due to changes in the calling thread's processor set or
changes in the lgroup hierarchy. A stale cookie is refreshed by calling the
lgrp_fini() function with the old cookie, followed by calling lgrp_init() to generate
a new cookie.

The lgrp_cookie_stale() function returns EINVAL when the given cookie is invalid.

Using lgrp_view()

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

The lgrp_view() function takes a cookie that represents a snapshot of the lgroup
hierarchy and returns the snapshot's view of the lgroup hierarchy. Snapshots that are
taken with the view LGRP_VIEW_CALLER contain only the resources that are available
to the calling thread. Snapshots that are taken with the view LGRP_VIEW_OS contain all
the resources that are available to the operating system.

The lgrp_view() function returns EINVAL when the given cookie is invalid.

Using 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.

#include <sys/lgrp_user.h>
int lgrp_nlgrps(lgrp_cookie_t cookie);

The lgrp_nlgrps() function takes a cookie that represents a snapshot of the lgroup
hierarchy and returns the number of lgroups available in the hierarchy.

If lgrp_array is not NULL and the value of lgrp_array_size is not zero,
the lgrp_parents() function fills the array with parent lgroup IDs until the
array is full or all parent lgroup IDs are in the array. The
root lgroup has zero parents. When the lgrp_parents() function is called for the root
lgroup, lgrp_array is not filled in.

The lgrp_parents() function returns EINVAL when the cookie is invalid. The lgrp_parents() function
returns ESRCH when the specified lgroup ID is not found.

Using 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.

If lgrp_array is not NULL and the value of lgrp_array_size is not zero,
the lgrp_children() function fills the array with child lgroup IDs until the
array is full or all child lgroup IDs are in the array.

The lgrp_children() function returns EINVAL when the cookie is invalid. The lgrp_children() function
returns ESRCH when the specified lgroup ID is not found.