Wiki code for plgrp(1M) proposed man page.

Hide Line numbers
1: |** plgrp - observe and affect home lgroup and lgroup affinities of threads**
2: 
3: * [[NAME>>#name]]
4: * [[SYNOPSIS>>#synopsis]]
5: * [[DESCRIPTION>>#description]]
6: ** [[OPTIONS>>#options]]
7: *** [[-a <lgroup list>>>#a__lgroup_list_]]
8: *** [[-A <lgroup list>/<none|weak|strong>[,...]>>#a__lgroup_list{{{___}}}none_weak_strong{{{_______}}}]]
9: *** [[-F>>#f]]
10: *** [[-h>>#h]]
11: *** [[-H <lgroup list>>>#h__lgroup_list_]]
12: * [[USAGE>>#usage]]
13: *** [[Specifying lgroups>>#specifying_lgroups]]
14: *** [[Specifying process and thread arguments>>#specifying_process_and_thread_arguments]]
15: * [[EXAMPLES>>#examples]]
16: * [[EXIT STATUS>>#exit_status]]
17: * [[ATTRIBUTES>>#attributes]]
18: * [[SEE ALSO>>#see_also]]
19: * [[WARNINGS>>#warnings]]
20: 
21: ----
22: 
23: = NAME
24: 
25: plgrp - observe and affect home lgroup and lgroup affinities of threads
26: 
27: ----
28: 
29: = SYNOPSIS
30: 
31: {{{
32: 
33:   plgrp [-F] [-h] <pid> | <core> [/<lwps>] ...
34: }}}
35: 
36: {{{
37: 
38:   plgrp [-F] -a <lgroup list> <pid>[/<lwps>] ...
39:   plgrp [-F] -H <lgroup list> <pid>[/<lwps>] ...
40:   plgrp [-F] -A <lgroup list>/<none|weak|strong>[,...] <pid>[/<lwps>] ...
41: }}}
42: 
43: ----
44: 
45: = DESCRIPTION
46: 
47: The plgrp utility can display or set the home lgroup and lgroup affinities for one or more processes and/or threads/lwps.
48: 
49: 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 {{code}}lgrpinfo(1){{/code}} for more about lgroups and the lgroup hierarchy).
50: 
51: 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.
52: 
53: 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 may be rehomed 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).
54: 
55: The different levels of lgroup affinities and their semantics are fully described in lgrp_affinity_set(3LGRP).
56: 
57: == OPTIONS
58: 
59: The following options are supported:
60: 
61: === -a <lgroup list>
62: 
63: Displays lgroup affinities of specified {{code}}process(es){{/code}} or {{code}}thread(s){{/code}} for the given lgroups.
64: 
65: === -A <lgroup list>/<none|weak|strong>[,...]
66: 
67: Sets affinity of specified {{code}}process(es){{/code}} or {{code}}thread(s){{/code}} to given lgroups. A comma separated list of <lgroups>/<affinity> assignments can be given to set several affinities at once.
68: 
69: === -F
70: 
71: Force. Grabs the target process even if another process has control.
72: 
73: 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.
74: 
75: === -h
76: 
77: Get home lgroup of specified {{code}}process(es){{/code}} and/or thread(s). This is the default when no options are given.
78: 
79: === -H <lgroup list>
80: 
81: Sets home lgroup of specified {{code}}process(es){{/code}} and/or thread(s).
82: 
83: This sets a strong affinity for the desired lgroup to rehome the thread(s). If more than one lgroup is specified, the plgrp utility will try to home the threads to the lgroups in a round robin fashion.
84: 
85: ----
86: 
87: = USAGE
88: 
89: === Specifying lgroups
90: 
91: The <lgroup list> is a comma separated list of one or more of the following:
92: 
93: {{{
94: 
95:     - lgroup ID
96:     - Range of lgroup IDs specified as
97:         <start lgroup ID>-<end lgroup ID>
98:     - "all"
99:     - "root"
100:     - "leaves"
101: }}}
102: 
103: The {{code}}all{{/code}} keyword represents all lgroup IDs in the system, the {{code}}root{{/code}} keyword represents the ID of the root lgroup and the {{code}}leaves{{/code}} keyword represents the IDs of all leaf lgroups (ie. lgroups which do not have any children).
104: 
105: === Specifying process and thread arguments
106: 
107: The plgrp utility takes one or more space separated processes or threads as arguments. Processes and threads can be specified in a manner similiar to the {{code}}proc(1){{/code}} tools. A process ID may be specified as an integer <pid> or /proc/<pid>. Shell expansions may 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(1).
108: 
109: Threads 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 {{code}}-{{/code}} and {{code}},{{/code}}. For example, <pid>/1,2,7-9 specifies threads 1, 2, 7, 8, and 9 of the process with <pid> as its process ID.
110: 
111: ----
112: 
113: = EXAMPLES
114: 
115: ; **Example 1:**
116: :  Getting home lgroup for shell
117: :
118: 
119: {{{
120:   % plgrp $$
121:      PID/LWPID    HOME
122:     3401/1        1
123: }}}
124: 
125: ; **Example 2:**
126: :  Setting home lgroup of multiple threads to the root lgroup
127: :
128: 
129: {{{
130:   % plgrp -H root `pgrep firefox`
131:      PID/LWPID    HOME
132:      918/1        1 => 0
133:      934/1        2 => 0
134:      934/2        1 => 0
135:      934/3        2 => 0
136:      934/625      1 => 0
137:      934/626      2 => 0
138:      934/624      2 => 0
139:      934/623      2 => 0
140:      934/630      1 => 0
141: }}}
142: 
143: ; **Example 3:**
144: :  Getting two threads’ affinities for lgroups 0-2
145: :
146: 
147: {{{
148:   % plgrp -a 0-2 101398/1 101337/1
149:      PID/LWPID    HOME  AFFINITY
150:   101398/1        1     0-2/none
151:   101337/1        1     0-2/none
152: }}}
153: 
154: ; **Example 4:**
155: :  Setting lgroup affinities
156: :
157: 
158: {{{
159:   % plgrp -A 0/weak,1/none,2/strong 101398
160:      PID/LWPID    HOME       AFFINITY
161:   101398/1        1 => 2     0,2/none => 2/strong,0/weak
162: }}}
163: 
164: ----
165: 
166: = EXIT STATUS
167: 
168: The following exit values are returned:
169: 
170: 1.
171: 1.
172: 1.
173: 
174: ----
175: 
176: = ATTRIBUTES
177: 
178: See {{code}}attributes(5){{/code}} for descriptions of the following attributes:
179: 
180: {{{
181: 
182:      {{{____________________________________________________________}}}
183:     |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
184:     |{{{_____________________________}}}|{{{_____________________________}}}|
185:     | Availability                |                             |
186:     |{{{_____________________________}}}|{{{_____________________________}}}|
187:     | Interface Stability         |                             |
188:     |{{{_____________________________}}}|{{{_____________________________}}}|
189:     | Command Syntax              | Unstable                    |
190:     |{{{_____________________________}}}|{{{_____________________________}}}|
191:     | Output Format(s)            | Unstable                    |
192:     |{{{_____________________________}}}|{{{_____________________________}}}|
193: }}}
194: 
195: ----
196: 
197: = SEE ALSO
198: 
199: lgrpinfo(1), madv.so.1(1), pmadvise(1), pmap(1), proc(1), prstat(1M), ps(1), lgrp_affinity_get(3LGRP), lgrp_affinity_set(3LGRP), lgrp_home(3LGRP), liblgrp(3LIB), {{code}}proc(4){{/code}}
200: 
201: ----
202: 
203: = WARNINGS
204: 
205: Like {{code}}proc(1){{/code}} tools, the plgrp utility stops its target processeswhile inspecting them and reporting the results when invoked with any option.
206: 
207: There are conditions under which processes may deadlock (see {{code}}proc(1){{/code}} for more details). 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.
208: 
209: A process being stopped by this tool can be identified by issuing /usr/bin/ps -eflL and looking for T in the first column. Notice that certain processes, for example, sched, can show the T status by default most of the time.
210: 
211: |** plgrp - observe and affect home lgroup and lgroup affinities of threads**
OpenSolaris

Top Menu

Wiki code for plgrp(1M) proposed man page.

Search

Collectives

Community Group

Project

User Group

Subsites

Community Group performance Pages
