1plgrp(1) User Commands plgrp(1)
2
6 plgrp - observe and affect home lgroup and lgroup affinities of threads
7
9 plgrp [-F] [-h] pid | core [/lwps] ...
10 plgrp [-F] -a lgroup_list pid[/lwps] ...
13 plgrp [-F] -H lgroup_list pid[/lwps] ...
16 plgrp [-F] -A lgroup_list/none | weak |strong [,...] pid
19 [/lwps] ...
20
23 plgrp displays or sets the home lgroup and lgroup affinities for one or
24 more processes, threads, or LWPs.
25 An lgroup represents the set of CPU and memory-like hardware devices
28 that are at most some distance (latency) apart from each other. Each
29 lgroup in the system is identified by a unique lgroup ID. The lgroups
30 are organized into a hierarchy to facilitate finding the nearest
31 resources (see lgrpinfo(1) for more about lgroups and the lgroup hier‐
32 archy).
33 By default, each thread is assigned a home lgroup upon creation. When
36 the system needs to allocate a CPU or memory resource for a thread, it
37 searches the lgroup hierarchy from the thread's home lgroup for the
38 nearest available resources to the thread's home.
39 Typically, the home lgroup for a thread is the lgroup for which the
42 thread has the most affinity. Initially, the system chooses a home
43 lgroup for each thread, but leaves the thread's affinity for that
44 lgroup set to none. If a thread sets a stronger affinity for an lgroup
45 in its processor set other than its home, the thread is rehomed to that
46 lgroup as long as the thread is not bound to a CPU. The thread can be
47 re-homed to the lgroup in its processor set with the next highest
48 affinity when the affinity (if any) for its home lgroup is removed (set
49 to none).
50 The different levels of lgroup affinities and their semantics are fully
53 described in lgrp_affinity_set(3LGRP).
54
56 Specifying lgroups
57 lgroup_list is a comma separated list of one or more of the following:
58 - lgroup_ID
60 - Range of lgroup_IDs specified as
61 <start lgroup_ID>-<end lgroup_ID>
62 - all
63 - root
64 - leaves
65 The all keyword represents all lgroup IDs in the system. The root key‐
70 word represents the ID of the root lgroup. The leaves keyword repre‐
71 sents the IDs of all leaf lgroups, that is, lgroups which do not have
72 any children.
73 Specifying Processes and Threads
75 plgrp takes one or more space separated processes or threads as argu‐
76 ments. Processes and threads can be specified in a manner similiar to
77 the proc(1) tools. A process ID may be specified as an integer pid or
78 /proc/pid. Shell expansions can be used to specify processes when
79 /proc/pid is used. For example, /proc/* can be used to specify all the
80 processes in the system. If a process ID is given alone, then all the
81 threads of the process are included as arguments to plgrp.
82 A thread can be explicitly specified with its process ID and thread ID
85 given together as pid/lwpid. Multiple threads of a process can be
86 selected at once by using the hyphen (-) and comma(,). For example,
87 pid/1,2,7-9 specifies threads 1, 2, 7, 8, and 9 of the process with pid
88 as its process ID.
89
91 The following options are supported:
92 -a lgroup_list
94 Display lgroup affinities of specified processes or threads for the
96 specified lgroup_list.
97 -A lgroup_list/none|weak|strong[,...]
100 Set affinity of specified processes or threads for the specified
102 lgroup_list.
103 A comma separated list of lgroups/affinity assignments can be given
105 to set several affinities at once.
106 -F
109 Force by grabbing the target process even if another process has
111 control. Caution should be exercised when using the -F flag. Impos‐
112 ing two controlling processes on one victim process can lead to
113 chaos. Safety is assured only when the primary controlling process
114 (typically a debugger) has stopped the victim process, but isn't
115 doing anything during the application of this proc tool. See WARN‐
116 INGS for more details.
117 -h
120 Get home lgroup of specified processes and/or threads. If no
122 options are specified, this is the default.
123 -H lgroup_list
126 Set home lgroup of specified processes and threads.
128 This sets a strong affinity for the desired lgroup to rehome the
130 threads. If more than one lgroup is specified, plgrp tries to home
131 the threads to the lgroups in a round robin fashion.
132
135 The following operands are supported:
136 lwps Specifies thread. See USAGE.
138 pid Specifies process ID. See USAGE.
141
144 Example 1 Getting the Home lgroup for the Shell
145 The following example gets the home lgroup for the shell:
148 % plgrp $$
151 PID/LWPID HOME
152 3401/1 1
153 Example 2 Setting the Home lgroup of Multiple Threads to the Root
157 lgroup
158 The following example sets the home lgroup of multiple threads to the
161 root lgroup:
162 % plgrp -H root `pgrep firefox`
165 PID/LWPID HOME
166 918/1 1 => 0
167 934/1 2 => 0
168 934/2 1 => 0
169 934/3 2 => 0
170 934/625 1 => 0
171 934/626 2 => 0
172 934/624 2 => 0
173 934/623 2 => 0
174 934/630 1 => 0
175 Example 3 Getting Two Threads' Affinities for lgroups 0-2
179 The following example gets two threads' affinities for lgroups 1-2:
182 % plgrp -a 0-2 101398/1 101337/1
185 PID/LWPID HOME AFFINITY
186 101398/1 1 0-2/none
187 101337/1 1 0-2/none
188 Example 4 Setting lgroup Affinities
192 The following example sets lgroup affinities:
195 % plgrp -A 0/weak,1/none,2/strong 101398
198 PID/LWPID HOME AFFINITY
199 101398/1 1 => 2 0,2/none => 2/strong,0/weak
200
204 The following exit values are returned:
205 0 Successful completion.
207 1 Syntax error. Nothing was changed.
210 2 Non-fatal error or interrupt. Something might have changed.
213
216 See attributes(5) for descriptions of the following attributes:
217 ┌─────────────────────────────┬─────────────────────────────┐
222 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
223 ├─────────────────────────────┼─────────────────────────────┤
224 │Availability │SUNWesu │
225 ├─────────────────────────────┼─────────────────────────────┤
226 │Interface Stability │See below. │
227 └─────────────────────────────┴─────────────────────────────┘
228 The command syntax is Unstable. The output formats are Unstable.
231
233 lgrpinfo(1), madv.so.1(1), pmadvise(1), pmap(1), proc(1), ps(1),
234 prstat(1M), lgrp_affinity_get(3LGRP), lgrp_affinity_set(3LGRP),
235 lgrp_home(3LGRP), liblgrp(3LIB), proc(4), attributes(5)
236
238 Like the proc(1) tools, the plgrp utility stops its target processes
239 while inspecting them and reports the results when invoked with any
240 option.
241 There are conditions under which processes can deadlock. A process can
244 do nothing while it is stopped. Stopping a heavily used process in a
245 production environment (even for a short amount of time) can cause
246 severe bottlenecks and even hangs of these processes, making them to be
247 unavailable to users. Thus, stopping a UNIX process in a production
248 environment should be avoided. See proc(1).
249 A process that is stopped by this tool might be identified by issuing
252 the following command:
253 /usr/bin/ps -eflL
255 and looking for a T in the first column of the output. Certain pro‐
260 cesses, for example, sched, can show the T status by default most of
261 the time.
262SunOS 5.11 8 Sep 2006 plgrp(1)