6 .TH LGRP_AFFINITY_GET 3LGRP "Apr 16, 2003"
7 .SH NAME
8 lgrp_affinity_get, lgrp_affinity_set \- get of set lgroup affinity
9 .SH SYNOPSIS
10 .LP
11 .nf
12 cc [ \fIflag \&.\|.\|.\fR ] \fIfile\fR\&.\|.\|. \fB-llgrp\fR [ \fIlibrary \&.\|.\|.\fR ]
13 #include <sys/lgrp_user.h>
14
15 \fBlgrp_affinity_t\fR \fBlgrp_affinity_get\fR(\fBidtype_t\fR \fIidtype\fR, \fBid_t\fR \fIid\fR,
16 \fBlgrp_id_t\fR \fIlgrp\fR);
17 .fi
18
19 .LP
20 .nf
21 \fBint\fR \fBlgrp_affinity_set\fR(\fBidtype_t\fR \fIidtype\fR, \fBid_t\fR \fIid\fR, \fBlgrp_id_t\fR \fIlgrp\fR,
22 \fBlgrp_affinity_t\fR \fIaffinity\fR);
23 .fi
24
25 .SH DESCRIPTION
26 .sp
27 .LP
28 The \fBlgrp_affinity_get()\fR function returns the affinity that the LWP or set
29 of LWPs specified by the \fIidtype\fR and \fIid\fR arguments have for the given
30 lgroup.
31 .sp
32 .LP
33 The \fBlgrp_affinity_set()\fR function sets the affinity that the LWP or set of
34 LWPs specified by \fIidtype\fR and \fIid\fR have for the given lgroup. The
35 lgroup affinity can be set to \fBLGRP_AFF_STRONG\fR, \fBLGRP_AFF_WEAK\fR, or
36 \fBLGRP_AFF_NONE\fR.
37 .sp
38 .LP
39 If the \fIidtype\fR is \fBP_PID\fR, the affinity is retrieved for one of the
40 LWPs in the process or set for all the LWPs of the process with process ID
41 (PID) \fIid\fR. The affinity is retrieved or set for the LWP of the current
42 process with LWP ID \fIid\fR if \fIidtype\fR is \fBP_LWPID\fR. If \fIid\fR is
43 \fBP_MYID\fR, then the current LWP or process is specified.
44 .sp
45 .LP
46 The operating system uses the lgroup affinities as advice on where to run a
47 thread and allocate its memory and factors this advice in with other
48 constraints. Processor binding and processor sets can restrict which lgroups a
49 thread can run on, but do not change the lgroup affinities.
50 .sp
51 .LP
52 Each thread can have an affinity for an lgroup in the system such that the
53 thread will tend to be scheduled to run on that lgroup and allocate memory from
54 there whenever possible. If the thread has affinity for more than one lgroup,
55 the operating system will try to run the thread and allocate its memory on the
56 lgroup for which it has the strongest affinity, then the next strongest, and so
57 on up through some small, system-dependent number of these lgroup affinities.
58 When multiple lgroups have the same affinity, the order of preference among
59 them is unspecified and up to the operating system to choose. The lgroup with
60 the strongest affinity that the thread can run on is known as its "home lgroup"
61 (see \fBlgrp_home\fR(3LGRP)) and is usually the operating system's first choice
62 of where to run the thread and allocate its memory.
63 .sp
64 .LP
65 There are different levels of affinity that can be specified by a thread for a
66 particuliar lgroup. The levels of affinity are the following from strongest to
67 weakest:
68 .sp
69 .in +2
70 .nf
71 LGRP_AFF_STRONG /* strong affinity */
72 LGRP_AFF_WEAK /* weak affinity */
73 LGRP_AFF_NONE /* no affinity */
74 .fi
75 .in -2
76
77 .sp
78 .LP
79 The \fBLGRP_AFF_STRONG\fR affinity serves as a hint to the operating system
80 that the calling thread has a strong affinity for the given lgroup. If this is
81 the thread's home lgroup, the operating system will avoid rehoming it to
82 another lgroup if possible. However, dynamic reconfiguration, processor
83 offlining, processor binding, and processor set binding and manipulation are
84 examples of events that can cause the operating system to change the thread's
85 home lgroup for which it has a strong affinity.
86 .sp
87 .LP
88 The \fBLGRP_AFF_WEAK\fR affinity is a hint to the operating system that the
89 calling thread has a weak affinity for the given lgroup. If a thread has a
90 weak affinity for its home lgroup, the operating system interpets this to mean
91 that thread does not mind whether it is rehomed, unlike \fBLGRP_AFF_STRONG\fR.
92 Load balancing, dynamic reconfiguration, processor binding, or processor set
93 binding and manipulation are examples of events that can cause the operating
94 system to change a thread's home lgroup for which it has a weak affinity.
95 .sp
96 .LP
97 The \fBLGRP_AFF_NONE\fR affinity signifies no affinity and can be used to
98 remove a thread's affinity for a particuliar lgroup. Initially, each thread
99 has no affinity to any lgroup. If a thread has no lgroup affinities set, the
100 operating system chooses a home lgroup for the thread with no affinity set.
101 .SH RETURN VALUES
102 .sp
103 .LP
104 Upon successful completion, \fBlgrp_affinity_get()\fR returns the affinity for
105 the given lgroup.
106 .sp
107 .LP
108 Upon successful completion, \fBlgrp_affinity_set()\fR return 0.
109 .sp
110 .LP
111 Otherwise, both functions return \(mi1 and set \fBerrno\fR to indicate the
112 error.
113 .SH ERRORS
114 .sp
115 .LP
116 The \fBlgrp_affinity_get()\fR and \fBlgrp_affinity_set()\fR functions will fail
117 if:
118 .sp
119 .ne 2
120 .na
121 \fB\fBEINVAL\fR\fR
122 .ad
123 .RS 10n
124 The specified lgroup, affinity, or ID type is not valid.
125 .RE
126
127 .sp
128 .ne 2
129 .na
130 \fB\fBEPERM\fR\fR
131 .ad
132 .RS 10n
133 The effective user of the calling process does not have appropriate privileges,
134 and its real or effective user ID does not match the real or effective user ID
135 of one of the LWPs.
136 .RE
137
138 .sp
139 .ne 2
140 .na
141 \fB\fBESRCH\fR\fR
142 .ad
143 .RS 10n
144 The specified lgroup or LWP(s) was not found.
145 .RE
146
147 .SH ATTRIBUTES
148 .sp
149 .LP
150 See \fBattributes\fR(5) for descriptions of the following attributes:
151 .sp
152
153 .sp
154 .TS
155 box;
156 c | c
157 l | l .
158 ATTRIBUTE TYPE ATTRIBUTE VALUE
159 _
160 Interface Stability Evolving
161 _
162 MT-Level MT-Safe
163 .TE
164
165 .SH SEE ALSO
166 .sp
167 .LP
168 \fBlgrp_home\fR(3LGRP), \fBliblgrp\fR(3LIB), \fBattributes\fR(5)
|
6 .TH LGRP_AFFINITY_GET 3LGRP "Apr 16, 2003"
7 .SH NAME
8 lgrp_affinity_get, lgrp_affinity_set \- get of set lgroup affinity
9 .SH SYNOPSIS
10 .LP
11 .nf
12 cc [ \fIflag \&.\|.\|.\fR ] \fIfile\fR\&.\|.\|. \fB-llgrp\fR [ \fIlibrary \&.\|.\|.\fR ]
13 #include <sys/lgrp_user.h>
14
15 \fBlgrp_affinity_t\fR \fBlgrp_affinity_get\fR(\fBidtype_t\fR \fIidtype\fR, \fBid_t\fR \fIid\fR,
16 \fBlgrp_id_t\fR \fIlgrp\fR);
17 .fi
18
19 .LP
20 .nf
21 \fBint\fR \fBlgrp_affinity_set\fR(\fBidtype_t\fR \fIidtype\fR, \fBid_t\fR \fIid\fR, \fBlgrp_id_t\fR \fIlgrp\fR,
22 \fBlgrp_affinity_t\fR \fIaffinity\fR);
23 .fi
24
25 .SH DESCRIPTION
26 .LP
27 The \fBlgrp_affinity_get()\fR function returns the affinity that the LWP or set
28 of LWPs specified by the \fIidtype\fR and \fIid\fR arguments have for the given
29 lgroup.
30 .sp
31 .LP
32 The \fBlgrp_affinity_set()\fR function sets the affinity that the LWP or set of
33 LWPs specified by \fIidtype\fR and \fIid\fR have for the given lgroup. The
34 lgroup affinity can be set to \fBLGRP_AFF_STRONG\fR, \fBLGRP_AFF_WEAK\fR, or
35 \fBLGRP_AFF_NONE\fR.
36 .sp
37 .LP
38 If the \fIidtype\fR is \fBP_PID\fR, the affinity is retrieved for one of the
39 LWPs in the process or set for all the LWPs of the process with process ID
40 (PID) \fIid\fR. The affinity is retrieved or set for the LWP of the current
41 process with LWP ID \fIid\fR if \fIidtype\fR is \fBP_LWPID\fR. If \fIid\fR is
42 \fBP_MYID\fR, then the current LWP or process is specified.
43 .sp
44 .LP
45 The operating system uses the lgroup affinities as advice on where to run a
46 thread and allocate its memory and factors this advice in with other
47 constraints. Processor binding and processor sets can restrict which lgroups a
48 thread can run on, but do not change the lgroup affinities.
49 .sp
50 .LP
51 Each thread can have an affinity for an lgroup in the system such that the
52 thread will tend to be scheduled to run on that lgroup and allocate memory from
53 there whenever possible. If the thread has affinity for more than one lgroup,
54 the operating system will try to run the thread and allocate its memory on the
55 lgroup for which it has the strongest affinity, then the next strongest, and so
56 on up through some small, system-dependent number of these lgroup affinities.
57 When multiple lgroups have the same affinity, the order of preference among
58 them is unspecified and up to the operating system to choose. The lgroup with
59 the strongest affinity that the thread can run on is known as its "home lgroup"
60 (see \fBlgrp_home\fR(3LGRP)) and is usually the operating system's first choice
61 of where to run the thread and allocate its memory.
62 .sp
63 .LP
64 There are different levels of affinity that can be specified by a thread for a
65 particular lgroup. The levels of affinity are the following from strongest to
66 weakest:
67 .sp
68 .in +2
69 .nf
70 LGRP_AFF_STRONG /* strong affinity */
71 LGRP_AFF_WEAK /* weak affinity */
72 LGRP_AFF_NONE /* no affinity */
73 .fi
74 .in -2
75
76 .sp
77 .LP
78 The \fBLGRP_AFF_STRONG\fR affinity serves as a hint to the operating system
79 that the calling thread has a strong affinity for the given lgroup. If this is
80 the thread's home lgroup, the operating system will avoid rehoming it to
81 another lgroup if possible. However, dynamic reconfiguration, processor
82 offlining, processor binding, and processor set binding and manipulation are
83 examples of events that can cause the operating system to change the thread's
84 home lgroup for which it has a strong affinity.
85 .sp
86 .LP
87 The \fBLGRP_AFF_WEAK\fR affinity is a hint to the operating system that the
88 calling thread has a weak affinity for the given lgroup. If a thread has a
89 weak affinity for its home lgroup, the operating system interpets this to mean
90 that thread does not mind whether it is rehomed, unlike \fBLGRP_AFF_STRONG\fR.
91 Load balancing, dynamic reconfiguration, processor binding, or processor set
92 binding and manipulation are examples of events that can cause the operating
93 system to change a thread's home lgroup for which it has a weak affinity.
94 .sp
95 .LP
96 The \fBLGRP_AFF_NONE\fR affinity signifies no affinity and can be used to
97 remove a thread's affinity for a particular lgroup. Initially, each thread
98 has no affinity to any lgroup. If a thread has no lgroup affinities set, the
99 operating system chooses a home lgroup for the thread with no affinity set.
100 .SH RETURN VALUES
101 .LP
102 Upon successful completion, \fBlgrp_affinity_get()\fR returns the affinity for
103 the given lgroup.
104 .sp
105 .LP
106 Upon successful completion, \fBlgrp_affinity_set()\fR return 0.
107 .sp
108 .LP
109 Otherwise, both functions return \(mi1 and set \fBerrno\fR to indicate the
110 error.
111 .SH ERRORS
112 .LP
113 The \fBlgrp_affinity_get()\fR and \fBlgrp_affinity_set()\fR functions will fail
114 if:
115 .sp
116 .ne 2
117 .na
118 \fB\fBEINVAL\fR\fR
119 .ad
120 .RS 10n
121 The specified lgroup, affinity, or ID type is not valid.
122 .RE
123
124 .sp
125 .ne 2
126 .na
127 \fB\fBEPERM\fR\fR
128 .ad
129 .RS 10n
130 The effective user of the calling process does not have appropriate privileges,
131 and its real or effective user ID does not match the real or effective user ID
132 of one of the LWPs.
133 .RE
134
135 .sp
136 .ne 2
137 .na
138 \fB\fBESRCH\fR\fR
139 .ad
140 .RS 10n
141 The specified lgroup or LWP(s) was not found.
142 .RE
143
144 .SH ATTRIBUTES
145 .LP
146 See \fBattributes\fR(5) for descriptions of the following attributes:
147 .sp
148
149 .sp
150 .TS
151 box;
152 c | c
153 l | l .
154 ATTRIBUTE TYPE ATTRIBUTE VALUE
155 _
156 Interface Stability Evolving
157 _
158 MT-Level MT-Safe
159 .TE
160
161 .SH SEE ALSO
162 .LP
163 \fBlgrp_home\fR(3LGRP), \fBliblgrp\fR(3LIB), \fBattributes\fR(5)
|