Go to main content

Oracle® Solaris 11.4 Programming Interfaces Guide

Exit Print View

Updated: November 2020
 
 

Locality Group Contents

The lgroup hierarchy organizes the domain's resources to simplify the process of locating the nearest resource. Leaf lgroups are defined with resources that have the least latency. Each of the successive ancestor lgroups of a given leaf lgroup contains the next nearest resources to its child lgroup. The root lgroup contains all of the resources that are in the domain.

The resources of a given lgroup are contained directly within that lgroup or indirectly within the leaf lgroups that the given lgroup encapsulates. Leaf lgroups directly contain their resources and do not encapsulate any other lgroups.

The following APIs retrieve information about the contents of a given lgroup.

Using lgrp_resources()

The lgrp_resources() function returns the number of resources contained in the specified lgroup.

#include <sys/lgrp_user.h>
int lgrp_resources(lgrp_cookie_t cookie, lgrp_id_t lgrp, lgrp_id_t *lgrpids,
                   uint_t count, lgrp_rsrc_t type);

The lgrp_resources() function takes a cookie that represents a snapshot of the lgroup hierarchy. This cookie is obtained from the lgrp_init() function. The lgrp_resources() function returns the number of resources that are in the lgroup with the ID that is specified by the value of the lgrp argument. The lgrp_resources() function represents the resources with a set of lgroups that directly contain CPU or memory resources. The lgrp_rsrc_t argument can have one of the following values:

LGRP_RSRC_CPU

The lgrp_resources() function returns the number of CPU resources.

LGRP_RSRC_MEM

The lgrp_resources() function returns the number of memory resources.

When the value passed in the lgrpids[] argument is not null and the count argument is not zero, the lgrp_resources() function stores lgroup IDs in the lgrpids[] array. The number of lgroup IDs stored in the array can be up to the value of the count argument.

The lgrp_resources() function returns EINVAL when the specified cookie, lgroup ID, or type are not valid. The lgrp_resources() function returns ESRCH when the function does not find the specified lgroup ID.

Using lgrp_cpus()

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

#include <sys/lgrp_user.h>
int lgrp_cpus(lgrp_cookie_t cookie, lgrp_id_t lgrp, processorid_t *cpuids,
              uint_t count, int content);

If the cpuid[] argument is not NULL and the CPU count is not zero, the lgrp_cpus() function fills the array with CPU IDs until the array is full or all the CPU IDs are in the array.

The content argument can have the following two values:

LGRP_CONTENT_ALL

The lgrp_cpus() function returns IDs for the CPUs in this lgroup and its child lgroups.

LGRP_CONTENT_DIRECT

The lgrp_cpus() function returns IDs for the CPUs in this lgroup only.

The lgrp_cpus() function returns EINVAL when the cookie, lgroup ID, or one of the flag is not valid. The lgrp_cpus() function returns ESRCH when the specified lgroup ID is not found. For more information, see the lgrp_cpus(3LGRP) man page.

Using lgrp_mem_size()

The lgrp_mem_size() 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.

#include <sys/lgrp_user.h>
lgrp_mem_size_t lgrp_mem_size(lgrp_cookie_t cookie, lgrp_id_t lgrp,
                              int type, int content)

The type argument can have the following two values:

LGRP_MEM_SZ_FREE

The lgrp_mem_size() function returns the amount of free memory in bytes.

LGRP_MEM_SZ_INSTALLED

The lgrp_mem_size() function returns the amount of installed memory in bytes.

The content argument can have the following two values:

LGRP_CONTENT_ALL

The lgrp_mem_size() function returns the amount of memory in this lgroup and this lgroup's descendants.

LGRP_CONTENT_DIRECT

The lgrp_mem_size() function returns the amount of memory in this lgroup only.

The lgrp_mem_size() function returns EINVAL when the cookie, lgroup ID, or one of the flag is not valid. The lgrp_mem_size() function returns ESRCH when the specified lgroup ID is not found. For more information, see the lgrp_mem_size(3LGRP) man page.