User Commands plgrp(1)
NAME
plgrp - observe and affect home lgroup and lgroup affinities
of threads
SYNOPSIS
plgrp [-F] [-h] pid core [/lwps] ...
plgrp [-F] -a lgrouplist pid[/lwps] ...
plgrp [-F] -H lgrouplist pid[/lwps] ...
plgrp [-F] -A lgrouplist/none weak strong [,...] pid
[/lwps] ...
DESCRIPTION
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 crea-
tion. 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 sys-
tem 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 seman-
tics are fully described in lgrpaffinityset(3LGRP).
SunOS 5.11 Last change: 8 Sep 2006 1
User Commands plgrp(1)
USAGE
Specifying lgroups
lgrouplist is a comma separated list of one or more of the
following:
- lgroupID
- Range of lgroupIDs specified as
-
- 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.
Specifying Processes and Threads
plgrp takes one or more space separated processes or threads
as arguments. Processes and threads can be specified in a
manner similiar 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.
OPTIONS
The following options are supported:
-a lgrouplist
Display lgroup affinities of specified processes or
threads for the specified lgrouplist.
-A lgrouplist/noneweakstrong[,...]
Set affinity of specified processes or threads for the
specified lgrouplist.
A comma separated list of lgroups/affinity assignments
SunOS 5.11 Last change: 8 Sep 2006 2
User Commands plgrp(1)
can be given to set several affinities at once.
-F
Force by grabbing the target process even if another
process has control. Caution should be exercised when
using the -F flag. Imposing two controlling processes on
one victim process can lead to chaos. Safety is assured
only when the primary controlling process (typically a
debugger) has stopped the victim process, but isn't
doing anything during the application of this proc tool.
See WARNINGS for more details.
-h
Get home lgroup of specified processes and/or threads.
If no options are specified, this is the default.
-H lgrouplist
Set home lgroup of specified processes and threads.
This sets a strong affinity for the desired lgroup to
rehome the threads. If more than one lgroup is speci-
fied, plgrp tries to home the threads to the lgroups in
a round robin fashion.
OPERANDS
The following operands are supported:
lwps Specifies thread. See USAGE.
pid Specifies process ID. See USAGE.
EXAMPLES
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
SunOS 5.11 Last change: 8 Sep 2006 3
User Commands plgrp(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 AFINITY
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 AFINITY
101398/1 1 => 2 0,2/none => 2/strong,0/weak
EXIT STATUS
The following exit values are returned:
SunOS 5.11 Last change: 8 Sep 2006 4
User Commands plgrp(1)
0 Successful completion.
1 Syntax error. Nothing was changed.
2 Non-fatal error or interrupt. Something might have
changed.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWesu
Interface Stability See below.
The command syntax is Unstable. The output formats are
Unstable.
SEE ALSO
lgrpinfo(1), madv.so.1(1), pmadvise(1), pmap(1), proc(1),
ps(1), prstat(1M), lgrpaffinityget(3LGRP),
lgrpaffinityset(3LGRP), lgrphome(3LGRP), liblgrp(3LIB),
proc(4), attributes(5)
WARNINGS
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:
SunOS 5.11 Last change: 8 Sep 2006 5
User Commands plgrp(1)
/usr/bin/ps -eflL
and looking for a T in the first column of the output. Cer-
tain processes, for example, sched, can show the T status by
default most of the time.
SunOS 5.11 Last change: 8 Sep 2006 6
|
