te
Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
plgrp - observe and affect home lgroup and lgroup affinities of threads

plgrp [-F] [-h] pid | core [/lwps] ...

plgrp [-F] -a lgroup_list pid[/lwps] ...

plgrp [-F] -H lgroup_list pid[/lwps] ...

plgrp [-F] -A lgroup_list/none | weak |strong [,...] pid
 [/lwps] ...

plgrp displays or sets the home lgroup and lgroup affinities for one or more processes, threads, or LWPs.

An lgroup represents the set of CPU and memory-like hardware devices that are at most some distance (latency) apart from each other. Each lgroup in the system is identified by a unique lgroup ID. The lgroups are organized into a hierarchy to facilitate finding the nearest resources (see lgrpinfo(1) for more about lgroups and the lgroup hierarchy).

By default, each thread is assigned a home lgroup upon creation. When the system needs to allocate a CPU or memory resource for a thread, it searches the lgroup hierarchy from the thread's home lgroup for the nearest available resources to the thread's home.

Typically, the home lgroup for a thread is the lgroup for which the thread has the most affinity. Initially, the system chooses a home lgroup for each thread, but leaves the thread's affinity for that lgroup set to none. If a thread sets a stronger affinity for an lgroup in its processor set other than its home, the thread is rehomed to that lgroup as long as the thread is not bound to a CPU. The thread can be re-homed to the lgroup in its processor set with the next highest affinity when the affinity (if any) for its home lgroup is removed (set to none).

The different levels of lgroup affinities and their semantics are fully described in lgrp_affinity_set(3LGRP).

lgroup_list is a comma separated list of one or more of the following:

- lgroup_ID
- Range of lgroup_IDs specified as
 <start lgroup_ID>-<end lgroup_ID>
- all
- root
- leaves

The all keyword represents all lgroup IDs in the system. The root keyword represents the ID of the root lgroup. The leaves keyword represents the IDs of all leaf lgroups, that is, lgroups which do not have any children.

plgrp takes one or more space separated processes or threads as arguments. Processes and threads can be specified in a manner similar to the proc(1) tools. A process ID may be specified as an integer pid or /proc/pid. Shell expansions can be used to specify processes when /proc/pid is used. For example, /proc/* can be used to specify all the processes in the system. If a process ID is given alone, then all the threads of the process are included as arguments to plgrp.

A thread can be explicitly specified with its process ID and thread ID given together as pid/lwpid. Multiple threads of a process can be selected at once by using the hyphen (-) and comma(,). For example, pid/1,2,7-9 specifies threads 1, 2, 7, 8, and 9 of the process with pid as its process ID.

The following options are supported: -a lgroup_list

-A lgroup_list/none|weak|strong [,...] -F -h -H lgroup_list

The following operands are supported: lwps

pid

Example 1 Getting the Home lgroup for the Shell

The following example gets the home lgroup for the shell:

% plgrp $$
PID/LWPID HOME
3401/1 1

Example 2 Setting the Home lgroup of Multiple Threads to the Root lgroup

The following example sets the home lgroup of multiple threads to the root lgroup:

% plgrp -H root `pgrep firefox`
 PID/LWPID HOME
 918/1 1 => 0
 934/1 2 => 0
 934/2 1 => 0
 934/3 2 => 0
 934/625 1 => 0
 934/626 2 => 0
 934/624 2 => 0
 934/623 2 => 0
 934/630 1 => 0

Example 3 Getting Two Threads' Affinities for lgroups 0-2

The following example gets two threads' affinities for lgroups 1-2:

% plgrp -a 0-2 101398/1 101337/1
PID/LWPID HOME AFFINITY
101398/1 1 0-2/none
101337/1 1 0-2/none

Example 4 Setting lgroup Affinities

The following example sets lgroup affinities:

% plgrp -A 0/weak,1/none,2/strong 101398
PID/LWPID HOME AFFINITY
101398/1 1 => 2 0,2/none => 2/strong,0/weak

The following exit values are returned: 0

1 2

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability See below.

The command syntax is Unstable. The output formats are Unstable.

lgrpinfo (1), madv.so.1 (1), pmadvise (1), pmap (1), proc (1), ps (1), lgrp_affinity_get (3LGRP), lgrp_affinity_set (3LGRP), lgrp_home (3LGRP), liblgrp (3LIB), proc (5), attributes (7), prstat (8)

Like the proc(1) tools, the plgrp utility stops its target processes while inspecting them and reports the results when invoked with any option.

There are conditions under which processes can deadlock. A process can do nothing while it is stopped. Stopping a heavily used process in a production environment (even for a short amount of time) can cause severe bottlenecks and even hangs of these processes, making them to be unavailable to users. Thus, stopping a UNIX process in a production environment should be avoided. See proc(1).

A process that is stopped by this tool might be identified by issuing the following command:

/usr/bin/ps -eflL

and looking for a T in the first column of the output. Certain processes, for example, sched, can show the T status by default most of the time.