1 '\" te 2 .\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. 3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. 4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. 5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] 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)