The APIs described in this section enable the calling thread to navigate the lgroup hierarchy.
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 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.
The lgrp_cookie_stale() function determines whether the snapshot of the lgroup hierarchy represented by the given cookie is current.
#include <sys/lgrp_user.h> int lgrp_cookie_stale(lgrp_cookie_t cookie);
The cookie returned by the lgrp_init() function can become stale depending on the view that the snapshot represents. A cookie returned by 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 returned by 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. For more information, see the lgrp_cookie_stale(3LGRP) man page.
The lgrp_view() function determines the view of the given lgroup hierarchy snapshot.
#include <sys/lgrp_user.h> lgrp_view_t lgrp_view(lgrp_cookie_t cookie);
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 taken with the view LGRP_VIEW_CALLER contain only the resources that are available to the calling thread. Snapshots 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. For more information, see the lgrp_view(3LGRP) man page.
The lgrp_nlgrps() function returns the number of lgroups 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.
The lgrp_nlgrps() function returns EINVAL when the cookie is invalid. For more information, see the lgrp_nlgrps(3LGRP) man page.
The lgrp_root() function returns the root lgroup ID.
#include <sys/lgrp_user.h> lgrp_id_t lgrp_root(lgrp_cookie_t cookie);
The lgrp_root() function takes a cookie that represents a snapshot of the lgroup hierarchy and returns the root lgroup ID. For more information, see the lgrp_root(3LGRP) man page.
The lgrp_parents() function takes a cookie that represents a snapshot of the lgroup hierarchy and returns the number of parent lgroups for the specified lgroup.
#include <sys/lgrp_user.h>
int lgrp_parents(lgrp_cookie_t cookie, lgrp_id_t child,
lgrp_id_t *lgrp_array, uint_t lgrp_array_size);
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. For more information, see the lgrp_parents(3LGRP) man page.
The lgrp_children() 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.
#include <sys/lgrp_user.h>
int lgrp_children(lgrp_cookie_t cookie, lgrp_id_t parent,
lgrp_id_t *lgrp_array, uint_t lgrp_array_size);
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. For more information, see the lgrp_children(3LGRP) man page.