PLGRP(1) 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 lgroup_list pid[/lwps] ...


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


plgrp [-F] -A lgroup_list/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 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).

USAGE

Specifying lgroups

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.

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 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.

OPTIONS

The following options are supported:

-a lgroup_list

Display lgroup affinities of specified processes or threads for
the specified lgroup_list.


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

Set affinity of specified processes or threads for the specified
lgroup_list.

A comma separated list of lgroups/affinity assignments 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 lgroup_list

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 specified, 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

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

EXIT STATUS

The following exit values are returned:

0
Successful completion.


1
Syntax error. Nothing was changed.


2
Non-fatal error or interrupt. Something might have changed.

ATTRIBUTES

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.

SEE ALSO

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)

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:

/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.

April 9, 2016 PLGRP(1)