test

Memory and Thread Placement Optimization Developer's Guide

Chapter 2 MPO Observability Tools

This chapter describes the tools that are available to use the MPO functionality that is available in the Oracle Solaris operating system.

This chapter discusses the following topics:

The pmadvise utility

The pmadvise utility applies rules to a process that define how that process uses memory. The pmadvise utility applies the rules, called advice, to the process with the madvise(3C) tool. This tool can apply advice to a specific subrange of locations in memory at a specific time. By contrast, the madv.so.1(1) tool applies the advice throughout the execution of the target program to all segments of a specified type.

The pmadvise utility has the following options:

-f

This option takes control of the target process. This option overrides the control of any other process. See the proc(1) manual page.

-o

This option specifies the advice to apply to the target process. Specify the advice in this format:

private=advice
shared=advice
heap=advice
stack=advice
address:length=advice

The value of the advice term can be one of the following:

normal
random
sequential
willneed
dontneed
free
access_lwp
access_many
access_default

You can specify an address and length to specify the subrange where the advice applies. Specify the address in hexadecimal notation and the length in bytes.

If you do not specify the length and the starting address refers to the start of a segment, the pmadvise utility applies the advice to that segment. You can qualify the length by adding the letters K, M, G, T, P, or E to specify kilobytes, megabytes, gigabytes, terabytes, or exabytes, respectively.

-v

This option prints verbose output in the style of the pmap(1) tool that shows the value and locations of the advice rules currently in force.

The pmadvise tool attempts to process all legal options. When the pmadvise tool attempts to process an option that specifies an illegal address range, the tool prints an error message and skips that option. When the pmadvise tool finds a syntax error, it quits without processing any options and prints a usage message.

When the advice for a specific region conflicts with the advice for a more general region, the advice for the more specific region takes precedence. Advice that specifies a particular address range has precedence over advice for the heap and stack regions, and advice for the heap and stack regions has precedence over advice for private and shared memory.

The advice rules in each of the following groups are mutually exclusive from other advice rules within the same group:

MADV_NORMAL, MADV_RANDOM, MADV_SEQUENTIAL
MADV_WILLNEED, MADV_DONTNEED, MADV_FREE   
MADV_ACCESS_DEFAULT, MADV_ACCESS_LWP, MADV_ACCESS_MANY

Using the madv.so.1 Shared Object

The madv.so.1 shared object enables the selective configuration of virtual memory advice for launched processes and their descendants. To use the shared object, the following string must be present in the environment:

LD_PRELOAD=$LD_PRELOAD:madv.so.1

The madv.so.1 shared object applies memory advice as specified by the value of the MADV environment variable. The MADV environment variable specifies the virtual memory advice to use for all heap, shared memory, and mmap regions in the process address space. This advice is applied to all created processes. The following values of the MADV environment variable affect resource allocation among lgroups:

access_default

This value resets the kernel's expected access pattern to the default.

access_lwp

This value advises the kernel that the next LWP to touch an address range is the LWP that will access that range the most. The kernel allocates the memory and other resources for this range and the LWP accordingly.

access_many

This value advises the kernel that many processes or LWPs will access memory randomly across the system. The kernel allocates the memory and other resources accordingly.

The value of the MADVCFGFILE environment variable is the name of a text file that contains one or more memory advice configuration entries in the form exec-name:advice-opts.

The value of exec-name is the name of an application or executable. The value of exec-name can be a full pathname, a base name, or a pattern string.

The value of advice-opts is of the form region=advice. The values of advice are the same as the values for the MADV environment variable. Replace region with any of the following legal values:

madv

Advice applies to all heap, shared memory, and mmap(2) regions in the process address space.

heap

The heap is defined to be the brk(2) area. Advice applies to the existing heap and to any additional heap memory allocated in the future.

shm

Advice applies to shared memory segments. See shmat(2) for more information on shared memory operations.

ism

Advice applies to shared memory segments that are using the SHM_SHARE_MMU flag. The ism option takes precedence over shm.

dsm

Advice applies to shared memory segments that are using the SHM_PAGEABLE flag. The dsm option takes precedence over shm.

mapshared

Advice applies to mappings established by the mmap() system call using the MAP_SHARED flag.

mapprivate

Advice applies to mappings established by the mmap() system call using the MAP_PRIVATE flag.

mapanon

Advice applies to mappings established by the mmap() system call using the MAP_ANON flag. The mapanon option takes precedence when multiple options apply.

The value of the MADVERRFILE environment variable is the name of the path where error messages are logged. In the absence of a MADVERRFILE location, the madv.so.1 shared object logs errors by using syslog(3C) with a LOG_ERR as the severity level and LOG_USER as the facility descriptor.

Memory advice is inherited. A child process has the same advice as its parent. The advice is set back to the system default advice after a call to exec(2) unless a different level of advice is configured using the madv.so.1 shared object. Advice is only applied to mmap() regions explicitly created by the user program. Regions established by the run-time linker or by system libraries that make direct system calls are not affected.

madv.so.1 Usage Examples

The following examples illustrate specific aspects of the madv.so.1 shared object.

Example 2–1 Setting Advice for a Set of Applications

This configuration applies advice to all ISM segments for applications with exec names that begin with foo.

$ LD_PRELOAD=$LD_PRELOAD:madv.so.1
$ MADVCFGFILE=madvcfg
$ export LD_PRELOAD MADVCFGFILE
$ cat $MADVCFGFILE
        foo*:ism=access_lwp
Example 2–2 Excluding a Set of Applications From Advice

This configuration sets advice for all applications with the exception of ls.

$ LD_PRELOAD=$LD_PRELOAD:madv.so.1
$ MADV=access_many
$ MADVCFGFILE=madvcfg
$ export LD_PRELOAD MADV MADVCFGFILE
$ cat $MADVCFGFILE
        ls:
Example 2–3 Pattern Matching in a Configuration File

Because the configuration specified in MADVCFGFILE takes precedence over the value set in MADV, specifying * as the exec-name of the last configuration entry is equivalent to setting MADV. This example is equivalent to the previous example.

$ LD_PRELOAD=$LD_PRELOAD:madv.so.1
$ MADVCFGFILE=madvcfg
$ export LD_PRELOAD MADVCFGFILE
$ cat $MADVCFGFILE
        ls:
        *:madv=access_many
Example 2–4 Advice for Multiple Regions

This configuration applies one type of advice for mmap() regions and different advice for heap and shared memory regions for applications whose exec() names begin with foo.

$ LD_PRELOAD=$LD_PRELOAD:madv.so.1
$ MADVCFGFILE=madvcfg
$ export LD_PRELOAD MADVCFGFILE
$ cat $MADVCFGFILE
        foo*:madv=access_many,heap=sequential,shm=access_lwp

The plgrp tool

The plgrp utility can display or set the home lgroup and lgroup affinities for one or more processes, threads, or lightweight processes (LWPs). The system assigns a home lgroup to each thread on creation. When the system allocates a CPU or memory resource to a thread, it searches the lgroup hierarchy from the thread's home lgroup for the nearest available resources to the thread's home.

The system chooses a home lgroup for each thread. The thread's affinity for its home lgroup is initially set to none, or no affinity. When a thread sets an affinity for an lgroup in its processor set that is higher than the thread's affinity for its home lgroup, the system moves the thread to that lgroup. The system does not move threads that are bound to a CPU. The system rehomes a thread to the lgroup in its processor set that has the highest affinity when the thread's affinity for its home lgroup is removed (set to none).

For a full description of the different levels of lgroup affinity and their semantics, see the lgrp_affinity_set(3LGRP) manual page.

The plgrp tool supports the following options:

-a lgroup list

This option displays the affinities of the processes or threads that you specify for the lgroups in the list.

-Algroup list/none|weak|strong[,...]

This option sets the affinity of the processes or threads that you specify for the lgroups in the list. You can use a comma separated list of lgroup/affinity assignments to set several affinities at once.

-F

This option takes control of the target process. This option overrides the control of any other process. See the proc(1) manual page.

-h

This option returns the home lgroup of the processes or threads that you specify. This is the default behavior of the plgrp tool when you do not specify any options.

-H lgroup list

This option sets the home lgroup of the processes or threads that you specify. This option sets a strong affinity for the listed lgroup. If you specify more than one lgroup, the plgrp utility will attempt to home the threads to the lgroups in a round robin fashion.

Specifying Lgroups

The value of the lgroup list variable is a comma separated list of one or more of the following attributes:

The all keyword represents all of the lgroup IDs in the system. The root keyword represents the ID of the root lgroup. The leaves keyword represents the IDs of all of the leaf lgroups. A leaf lgroup is an lgroup that does not have any children.

Specifying Process and Thread Arguments

The plgrp utility takes one or more space-separated processes or threads as arguments. You can specify processes and threads in a the same syntax that the proc(1) tools use. You can specify a process ID as an integer, with the syntax pid or /proc/pid. You can use shell expansions with the /proc/pid syntax. When you give a process ID alone, the arguments to the plgrp utility include all of the threads of that process.

You can specify a thread explicitly by specifying the process ID and thread ID with the syntax pid/lwpid. You can specify multiple threads of a process by defining ranges with can be selected at once by using the - character to define a range, or with a comma-separated list. To specify threads 1, 2, 7, 8, and 9 of a process whose process ID is pid, use the syntax pid/1,2,7-9.

The lgrpinfo Tool

The lgrpinfo tool prints information about the lgroup hierarchy, contents, and characteristics. The lgrpinfo tool is a Perl script that requires the Solaris::Lgrp module. This tool uses the liblgrp(3LIB) API to get the information from the system and displays it in the human-readable form.

The lgrpinfo tool prints general information about all of the lgroups in the system when you call it without any arguments. When you pass lgroup IDs to the lgrpinfo tool at the command line, the tool returns information about the lgroups that you specify. You can specify lgroups with their lgroup IDs or with one of the following keywords:

all

This keyword specifies all lgroups and is the default behavior.

root

This keyword specifies the root lgroup.

leaves

This keyword specifies all of the leaf lgroups. A leaf lgroup is an lgroup that has no children in the lgroup hierarchy.

intermediate

This keyword specifies all of the intermediate lgroups. An intermediate lgroup is an lgroup that has a parent and children.

When the lgrpinfo tool receives an invalid lgroup ID, the tool prints a message with the invalid ID and continues processing any other lgroups that are passed in the command line. When the lgrpinfo tool finds no valid lgroups in the arguments, it exits with a status of 2.

Options for the lgrpinfo Tool

When you call the lgrpinfo tool without any arguments, the tool's behavior is equivalent to using the options -celmrt all. The valid options for the lgrpinfo tool are:

-a

This option prints the topology, CPU, memory, load and latency information for the specified lgroup IDs. This option combines the behaviors of the -tcemrlL options, unless you also specify the -T option. When you specify the -T option, the behavior of the -a option does not include the behavior of the -t option.

-c

This option prints the CPU information.

-C

This option replaces each lgroup in the list with its children. You cannot combine this option with the -P or -T options. When you do not specify any arguments, the tool applies this option to all lgroups.

-e

This option prints lgroup load averages for leaf lgroups.

-G

This option prints the OS view of the lgroup hierarchy. The tool's default behavior displays the caller's view of the lgroup hierarchy. The caller's view only includes the resources that the caller can use. See the lgrp_init(3LGRP) manual page for more details on the OS and caller's view.

-h

This option prints the help message for the tool.

-I

This option prints only IDs that match the IDs you specify. You can combine this option with the -c, -G, -C, or -P options. When you specify the -c option, the tool prints the list of CPUs that are in all of the matching lgroups. When you do not specify the -c option, the tool displays the IDs for the matching lgroups. When you do not specify any arguments, the tool applies this option to all lgroups.

-l

This option prints information about lgroup latencies. The latency value given for each lgroup is defined by the operating system and is platform-specific. It can only be used for relative comparison of lgroups on the running system. It does not necessarily represent the actual latency between hardware devices and may not be applicable across platforms.

-L

This option prints the lgroup latency table. This table shows the relative latency from each lgroup to each of the other lgroups.

-m

This option prints memory information. The tool reports memory sizes in the units that give a size result in the integer range from 0 to 1023. You can override this behavior by using the -u option. The tool will only display fractional results for values smaller than 10.

-P

This option replaces each lgroup in the list with its parent or parents. You cannot combine this option with the -C or -T options. When you do not specify any arguments, the tool applies this option to all lgroups.

-r

This option prints information about lgroup resources. When you specify the -T option, the tool displays information about the resources of the intermediate lgroups only.

-t

This option prints information about lgroup topology.

-T

This option prints the lgroup topology of a system graphically, as a tree. You can only use this option with the -a, -c, -e, -G, -l, -L, -m, -r, and -u options. To restrict the output to intermediate lgroups, use the -r option. Omit the -t option when you combine the -T option with the -a option. This option does not print information for the root lgroup unless it is the only lgroup.

-uunits

This option specifies memory units. The value of the units argument can be b, k, m, g, t, p, or e for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, or exabytes, respectively.

The Solaris::lgrp Module

This Perl module provides a Perl interface to the lgroup APIs that are in liblgrp. This interface provides a way to traverse the lgroup hierarchy, discover its contents and characteristics, and set a thread's affinity for an lgroup. The module gives access to various constants and functions defined in the lgrp_user.h header file. The module provides the procedural interface and the object interface to the library.

The default behavior of this module does not export anything. You can use the following tags to selectively import the constants and functions that are defined in this module:

:LGRP_CONSTANTS

LGRP_AFF_NONE, LGRP_AFF_STRONG, LGRP_AFF_WEAK, LGRP_CONTENT_DIRECT, LGRP_CONTENT_HIERARCHY, LGRP_MEM_SZ_FREE, LGRP_MEM_SZ_INSTALLED, LGRP_VER_CURRENT, LGRP_VER_NONE, LGRP_VIEW_CALLER, LGRP_VIEW_OS, LGRP_NONE, LGRP_RSRC_CPU, LGRP_RSRC_MEM, LGRP_CONTENT_ALL, LGRP_LAT_CPU_TO_MEM

:PROC_CONSTANTS

P_PID, P_LWPID, P_MYID

:CONSTANTS

:LGRP_CONSTANTS, :PROC_CONSTANTS

:FUNCTIONS

lgrp_affinity_get(), lgrp_affinity_set(), lgrp_children(), lgrp_cookie_stale(), lgrp_cpus(), lgrp_fini(), lgrp_home(), lgrp_init(), lgrp_latency(), lgrp_latency_cookie(), lgrp_mem_size(), lgrp_nlgrps(), lgrp_parents(), lgrp_root(), lgrp_version(), lgrp_view(), lgrp_resources(), lgrp_lgrps(), lgrp_leaves(), lgrp_isleaf(), lgrp_lgrps(), lgrp_leaves().

:ALL()

:CONSTANTS(), :FUNCTIONS()

The Perl module has the following methods:

You can export constants with the :CONSTANTS or :ALL tags. You can use any of the constants in the following list in Perl programs.

When an underlying library function fails, the functions in this module return either undef or an empty list. The module can use the following error codes:

EINVAL

The value supplied is not valid.

ENOMEM

There was not enough system memory to complete an operation.

ESRCH

The specified process or thread was not found.

EPERM

The effective user of the calling process does not have the appropriate privileges, and its real or effective user ID does not match the real or effective user ID of one of the threads.

Functions in the Solaris::lgrp Module

lgrp_init([LGRP_VIEW_CALLER | LGRP_VIEW_OS])

This function initializes the lgroup interface and takes a snapshot of the lgroup hierarchy with the given view. Given the view, the lgrp_init() function returns a cookie that represents this snapshot of the lgroup hierarchy. Use this cookie with the other routines in the lgroup interface that require the lgroup hierarchy. Call the lgrp_fini() function with this cookie when the system no longer needs the hierarchy snapshot. Unlike the lgrp_init(3LGRP) function, this function assumes a value of LGRP_VIEW_OS as the default if the system provides no view. This function returns a cookie upon successful completion. If the lgrp_init function does not complete successfully, it returns a value of undef and sets $! to indicate the error. See the man page for the lgrp_init(3LGRP) function for more information.

lgrp_fini($cookie)

This function takes a cookie, frees the snapshot of the lgroup hierarchy that the lgrp_init() function created, and cleans up anything else that the lgrp_init() function set up. After calling this function, do not use the cookie that the lgroup interface returns. This function returns 1 upon successful completion. If the lgrp_fini function does not complete successfully, it returns a value of undef and sets $! to indicate the error. See the man page for the lgrp_fini(3LGRP) function for more information.

lgrp_view($cookie)

This function takes a cookie that represents the snapshot of the lgroup hierarchy and returns the snapshot's view of the lgroup hierarchy. If the given view is LGRP_VIEW_CALLER, the snapshot contains only the resources that are available to the caller. When the view is LGRP_VIEW_OS, the snapshot contains the resources that are available to the operating system. This function returns the view for the snapshot of the lgroup hierarchy that is represented by the given cookie upon successful completion. If the lgrp_view function does not complete successfully, it returns a value of undef and sets $! to indicate the error. See the man page for the lgrp_view(3LGRP) function for more information.

lgrp_home($idtype, $id)

This function returns the home lgroup for the given process or thread. To specify a process, give the $idtype argument the value P_PID and give the $id argument the value of the process id. To specify a thread, give the $idtype argument the value P_LWPID and give the $id argument the value of the thread's LWP id. To specify the current process or thread, give the $id argument the value P_MYID. This function returns the id of the home lgroup of the specified process or thread upon successful completion. If the lgrp_home function does not complete successfully, it returns a value of undef and sets $! to indicate the error. See the man page for the lgrp_home(3LGRP) function for more information.

lgrp_cookie_stale($cookie)

This function returns the staleness status of the specified cookie upon successful completion. If the lgrp_cookie_stale function does not complete successfully, it returns a value of undef and sets $! to indicate the error. This function fails and returns EINVAL if the cookie is not valid. See the man page for the lgrp_cookie_stale(3LGRP) function for more information.

lgrp_cpus($cookie, $lgrp, $context)

This function takes a cookie that represents a snapshot of the lgroup hierarchy and returns the list of CPUs that are in the lgroup that is specified by the $lgrp argument. Give the $context argument the value LGRP_CONTENT_HIERARCHY to make the lgrp_cpus() function return the list of all the CPUs that are in the specified lgroup, including child lgroups. Give the $context() argument the value LGRP_CONTENT_DIRECT to make the lgrp_cpus() function return the list of CPUs that are directly contained in the specified lgroup. This function returns the number of CPUs that are in the specified lgroup when you call it in a scalar context. If the lgrp_cpus function does not complete successfully when you call it in a scalar context, it returns a value of undef and sets $! to indicate the error. If the lgrp_cpus function does not complete successfully when you call it in a list context, it returns the empty list and sets $! to indicate the error. See the man page for the lgrp_cpus(3LGRP) function for more information.

lgrp_children($cookie, $lgrp)

This function takes a cookie that represents a snapshot of the lgroup hierarchy and returns the list of lgroups that are children of the specified lgroup. When called in scalar context, the lgrp_children() function returns the number of children lgroups for the specified lgroup when you call it in a scalar context. If the lgrp_children function does not complete successfully when you call it in a scalar context, it returns a value of undef and sets $! to indicate the error. If the lgrp_children function does not complete successfully when you call it in a list context, it returns the empty list and sets $! to indicate the error. See the man page for the lgrp_children(3LGRP) function for more information.

lgrp_parents($cookie, $lgrp)

This function takes a cookie that represents a snapshot of the lgroup hierarchy and returns the list of parent groups of the specified lgroup. When called in scalar context, the lgrp_parents() function returns the number of parent lgroups for the specified lgroup when you call it in a scalar context. If the lgrp_parents function does not complete successfully when you call it in a scalar context, it returns a value of undef and sets $! to indicate the error. If the lgrp_parents function does not complete successfully when you call it in a list context, it returns the empty list and sets $! to indicate the error. See the man page for the lgrp_parents(3LGRP) function for more information.

lgrp_nlgrps($cookie)

This function takes a cookie that represents a snapshot of the lgroup hierarchy. It returns the number of lgroups in the hierarchy. This number is always at least one. If the lgrp_nlgrps function does not complete successfully, it returns a value of undef and sets the value of $! to EINVAL to indicate that the cookie is invalid. See the man page for the lgrp_nlgrps(3LGRP) function for more information.

lgrp_root($cookie)

This function returns the ID of the root lgroup. If the lgrp_root function does not complete successfully, it returns a value of undef and sets the value of $! to EINVAL to indicate that the cookie is invalid. See the man page for the lgrp_root(3LGRP) function for more information.

lgrp_mem_size($cookie, $lgrp, $type, $content)

This function takes a cookie that represents a snapshot of the lgroup hierarchy. The function returns the memory size of the given lgroup in bytes. Set the value of the $type argument to LGRP_MEM_SZ_FREE to have the lgrp_mem_size() function return the amount of free memory. Set the value of the $type argument to LGRP_MEM_SZ_INSTALLED to have the lgrp_mem_size() function return the amount of installed memory. Set the value of the $content argument to LGRP_CONTENT_HIERARCHY to have the lgrp_mem_size() function return results for the specified lgroup and each of its child lgroups. Set the value of the $content argument to LGRP_CONTENT_DIRECT to have the lgrp_mem_size() function return results for the specified lgroup only. This function returns the memory size in bytes upon successful completion, the size in bytes is returned. If the lgrp_mem_size function does not complete successfully, it returns a value of undef and sets $! to indicate the error. See the man page for the lgrp_mem_size(3LGRP) function for more information.

lgrp_version([VERSION])

This function takes an interface version number as the value of the VERSION argument and returns an lgroup interface version. To discover the current lgroup interface version, pass the value of LGRP_VER_CURRENT or LGRP_VER_NONE in the VERSION argument. The lgrp_version() function returns the requested version if the system supports that version. The lgrp_version() function returns LGRP_VER_NONE if the system does not supports the request version. The lgrp_version() function returns the current version of the library when you call the function with LGRP_VER_NONE as the value of the VERSION argument. This code fragment tests whether the version of the interface used by the caller is supported:

lgrp_version(LGRP_VER_CURRENT) == LGRP_VER_CURRENT or
             die("Built with unsupported lgroup interface");

See the man page for the lgrp_version(3LGRP) function for more information.

lgrp_affinity_set($idtype, $id, $lgrp, $affinity)

This function sets the affinity that the LWPs you specify with the $idtype and $id arguments have for the given lgroup. You can set the lgroup affinity to LGRP_AFF_STRONG, LGRP_AFF_WEAK, or LGRP_AFF_NONE. When the value of the $idtype argument is P_PID, this function sets the affinity for all the LWPs of the process with the process id specified in the $id argument. The lgrp_affinity_set() function sets the affinity for the LWP of the current process with LWP id $id when the value of the $idtype argument is P_LWPID. You can specify the current LWP or process by assigning the $id argument a value of P_MYID. This function returns 1 upon successful completion. If the lgrp_affinity_set function does not complete successfully, it returns a value of undef and sets $! to indicate the error. See the man page for the lgrp_affinity_set(3LGRP) function for more information.

lgrp_affinity_get($idtype, $id, $lgrp)

This function retrieves the affinity that the LWPs you specify with the $idtype and $id arguments have for the given lgroup. When the value of the $idtype argument is P_PID, this function retrieves the affinity for one of the LWPs in the process. The lgrp_affinity_get() function retrieves the affinity for the LWP of the current process with LWP id $id when the value of the $idtype argument is P_LWPID. You can specify the current LWP or process by assigning the $id argument a value of P_MYID. This function returns 1 upon successful completion. If the lgrp_affinity_get function does not complete successfully, it returns a value of undef and sets $! to indicate the error. See the man page for the lgrp_affinity_get(3LGRP) function for more information.

lgrp_latency_cookie($cookie, $from, $to, [$between=LGRP_LAT_CPU_TO_MEM])()

This function takes a cookie that represents a snapshot of the lgroup hierarchy and returns the latency value between a hardware resource in the $from lgroup to a hardware resource in the $to lgroup. This function returns the latency value within a given lgroup when the values of the $from and $to arguments are identical. Set the value of the optional $between argument to LGRP_LAT_CPU_TO_MEM to specify the hardware resources to measure the latency between. LGRP_LAT_CPU_TO_MEM represents the latency from CPU to memory and is the only valid value for this argument in this release. This function returns 1 upon successful completion. If the lgrp_latency_cookie function does not complete successfully, it returns a value of undef and sets $! to indicate the error. See the man page for the lgrp_latency_cookie(3LGRP) function for more information.

lgrp_latency($from, $to)()

The function is similar to the lgrp_latency_cookie() function, but returns the latency between the given lgroups at the given instant in time. Because the system dynamically reallocates and frees lgroups, this function's results are not always consistent across calls. This function is deprecated. Use the lgrp_latency_cookie() function instead. See the man page for the lgrp_latency(3LGRP) function for more information.

lgrp_resources($cookie, $lgrp, $type)()

This function is only available for version 2 of the API. When you call this function with version 1 of the API, the lgrp_resources() function returns undef or the empty list and sets the value of $! to EINVAL. This function returns the list of lgroups that directly contain the specified type of resources. The resources are represented by a set of lgroups in which each lgroup directly contains CPU and/or memory resources. To specify CPU resources, set the value of the $type argument to LGRP_RSRC_CPU. To specify memory resources, set the value of the $type argument to LGRP_RSRC_MEM. If the lgrp_resources function does not complete successfully, it returns a value of undef or the empty list and sets $! to indicate the error. See the man page for the lgrp_resources(3LGRP) function for more information.

lgrp_lgrps($cookie, [$lgrp])()

This function returns the list of all of the lgroups in a hierarchy, starting from the lgroup specified in the $lgrp argument. This function uses the value returned by the lgrp_root($cookie) function when the $lgrp argument has no value. The lgrp_lgrps() function returns the empty list on failure. This function returns the total number of lgroups in the system when you call it in a scalar context.

lgrp_leaves($cookie, [$lgrp])()

This function returns the list of all leaf lgroups in a hierarchy that starts from the lgroup specified in the $lgrp argument. This function uses the value returned by the lgrp_root($cookie) function when the $lgrp argument has no value. The lgrp_leaves() function returns undef or the empty list on failure. This function returns the total number of leaf lgroups in the system when you call it in a scalar context.

lgrp_isleaf($cookie, $lgrp)()

This function returns True if the lgroup specified by the value of the $lgrp argument is a leaf lgroup. Leaf lgroups have no children. The lgrp_isleaf() function returns False if the specified lgroup is not a leaf lgroup.

Object Methods in the Solaris::lgrp Module

new([$view])

This method creates a new Sun::Solaris::Lgrp object. An optional argument is passed to the lgrp_init() function. This method uses a value for the $view argument of LGRP_VIEW_OS by default.

cookie()

This function returns a transparent cookie that is passed to functions that accept a cookie.

version([$version])

This method returns the current version of the liblgrp(3LIB) library when you call it without an argument. This is a wrapper for the lgrp_version() function with LGRP_VER_NONE as the default value of the $version argument.

stale()

This method returns T if the lgroup information in the object is stale. This method returns F in all other cases. The stale method is a wrapper for the lgrp_cookie_stale() function.

view()

This method returns the snapshot's view of the lgroup hierarchy. The view() method is a wrapper for the lgrp_view() function.

root()

This method returns the root lgroup. The root() method is a wrapper for the lgrp_root() function.

children($lgrp)

This method returns the list of lgroups that are children of the specified lgroup. The children method is a wrapper for the lgrp_children() function.

parents($lgrp)

This method returns the list of lgroups that are parents of the specified lgroup. The parents method is a wrapper for the lgrp_parents() function.

nlgrps()

This method returns the number of lgroups in the hierarchy. The nlgrps() method is a wrapper for the lgrp_nlgrps() function.

mem_size($lgrp, $type, $content)

This method returns the memory size of the given lgroup in bytes. The mem_size method is a wrapper for the lgrp_mem_size() function.

cpus($lgrp, $context)

This method returns the list of CPUs that are in the lgroup specified by the $lgrp argument. The cpus method is a wrapper for the lgrp_cpus() function.

resources($lgrp, $type)

This method returns the list of lgroups that directly contain resources of the specified type. The resources method is a wrapper for the lgrp_resources() function.

home($idtype, $id)

This method returns the home lgroup for the given process or thread. The home method is a wrapper for the lgrp_home() function.

affinity_get($idtype, $id, $lgrp)

This method returns the affinity that the LWP has to a given lgroup. The affinity_get() method is a wrapper for the lgrp_affinity_get() function.

affinity_set($idtype, $id, $lgrp, $affinity)

This method sets the affinities that the LWPs specified by the $idtype and $id arguments have for the given lgroup. The affinity_set() method is a wrapper for the lgrp_affinity_set() function.

lgrps([$lgrp])

This method returns the list of all of the lgroups in a hierarchy starting from the lgroup specified by the value of the $lgrp argument. The hierarchy starts from the root lgroup when you do not specify a value for the $lgrp argument. The lgrps() method is a wrapper for the lgrp_lgrps() function.

leaves([$lgrp])

This method returns the list of all of the leaf lgroups in a hierarchy starting from the lgroup specified by the value of the $lgrp argument. The hierarchy starts from the root lgroup when you do not specify a value for the $lgrp argument. The leaves() method is a wrapper for the lgrp_leaves() function.

isleaf($lgrp)

This method returns True if the lgroup specified by the value of the $lgrp argument is a leaf lgroup. A leaf lgroup has no children. This method returns False in all other cases. The isleaf method is a wrapper for the lgrp_isleaf function.

latency($from, $to)

This method returns the latency value between a hardware resource in the lgroup specified by the $from argument to a hardware resource in the lgroup specified by the $to argument. The latency method uses the lgrp_latency() function in version 1 of liblgrp. The latency method uses the lgrp_latency_cookie() function in newer versions of liblgrp.