1 LGRP_AFFINITY_GET(3LGRP) Locality Group Library Functions 2 3 4 5 NAME 6 lgrp_affinity_get, lgrp_affinity_set - get of set lgroup affinity 7 8 SYNOPSIS 9 cc [ flag ... ] file... -llgrp [ library ... ] 10 #include <sys/lgrp_user.h> 11 12 lgrp_affinity_t lgrp_affinity_get(idtype_t idtype, id_t id, 13 lgrp_id_t lgrp); 14 15 16 int lgrp_affinity_set(idtype_t idtype, id_t id, lgrp_id_t lgrp, 17 lgrp_affinity_t affinity); 18 19 20 DESCRIPTION 21 The lgrp_affinity_get() function returns the affinity that the LWP or 22 set of LWPs specified by the idtype and id arguments have for the given 23 lgroup. 24 25 26 The lgrp_affinity_set() function sets the affinity that the LWP or set 27 of LWPs specified by idtype and id have for the given lgroup. The 28 lgroup affinity can be set to LGRP_AFF_STRONG, LGRP_AFF_WEAK, or 29 LGRP_AFF_NONE. 30 31 32 If the idtype is P_PID, the affinity is retrieved for one of the LWPs 33 in the process or set for all the LWPs of the process with process ID 34 (PID) id. The affinity is retrieved or set for the LWP of the current 35 process with LWP ID id if idtype is P_LWPID. If id is P_MYID, then the 36 current LWP or process is specified. 37 38 39 The operating system uses the lgroup affinities as advice on where to 40 run a thread and allocate its memory and factors this advice in with 41 other constraints. Processor binding and processor sets can restrict 42 which lgroups a thread can run on, but do not change the lgroup 43 affinities. 44 45 46 Each thread can have an affinity for an lgroup in the system such that 47 the thread will tend to be scheduled to run on that lgroup and allocate 48 memory from there whenever possible. If the thread has affinity for 49 more than one lgroup, the operating system will try to run the thread 50 and allocate its memory on the lgroup for which it has the strongest 51 affinity, then the next strongest, and so on up through some small, 52 system-dependent number of these lgroup affinities. When multiple 53 lgroups have the same affinity, the order of preference among them is 54 unspecified and up to the operating system to choose. The lgroup with 55 the strongest affinity that the thread can run on is known as its "home 56 lgroup" (see lgrp_home(3LGRP)) and is usually the operating system's 57 first choice of where to run the thread and allocate its memory. 58 59 60 There are different levels of affinity that can be specified by a 61 thread for a particular lgroup. The levels of affinity are the 62 following from strongest to weakest: 63 64 LGRP_AFF_STRONG /* strong affinity */ 65 LGRP_AFF_WEAK /* weak affinity */ 66 LGRP_AFF_NONE /* no affinity */ 67 68 69 70 The LGRP_AFF_STRONG affinity serves as a hint to the operating system 71 that the calling thread has a strong affinity for the given lgroup. If 72 this is the thread's home lgroup, the operating system will avoid 73 rehoming it to another lgroup if possible. However, dynamic 74 reconfiguration, processor offlining, processor binding, and processor 75 set binding and manipulation are examples of events that can cause the 76 operating system to change the thread's home lgroup for which it has a 77 strong affinity. 78 79 80 The LGRP_AFF_WEAK affinity is a hint to the operating system that the 81 calling thread has a weak affinity for the given lgroup. If a thread 82 has a weak affinity for its home lgroup, the operating system interpets 83 this to mean that thread does not mind whether it is rehomed, unlike 84 LGRP_AFF_STRONG. Load balancing, dynamic reconfiguration, processor 85 binding, or processor set binding and manipulation are examples of 86 events that can cause the operating system to change a thread's home 87 lgroup for which it has a weak affinity. 88 89 90 The LGRP_AFF_NONE affinity signifies no affinity and can be used to 91 remove a thread's affinity for a particular lgroup. Initially, each 92 thread has no affinity to any lgroup. If a thread has no lgroup 93 affinities set, the operating system chooses a home lgroup for the 94 thread with no affinity set. 95 96 RETURN VALUES 97 Upon successful completion, lgrp_affinity_get() returns the affinity 98 for the given lgroup. 99 100 101 Upon successful completion, lgrp_affinity_set() return 0. 102 103 104 Otherwise, both functions return -1 and set errno to indicate the 105 error. 106 107 ERRORS 108 The lgrp_affinity_get() and lgrp_affinity_set() functions will fail if: 109 110 EINVAL 111 The specified lgroup, affinity, or ID type is not valid. 112 113 114 EPERM 115 The effective user of the calling process does not have 116 appropriate privileges, and its real or effective user ID 117 does not match the real or effective user ID of one of the 118 LWPs. 119 120 121 ESRCH 122 The specified lgroup or LWP(s) was not found. 123 124 125 ATTRIBUTES 126 See attributes(5) for descriptions of the following attributes: 127 128 129 130 131 +--------------------+-----------------+ 132 | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 133 +--------------------+-----------------+ 134 |Interface Stability | Evolving | 135 +--------------------+-----------------+ 136 |MT-Level | MT-Safe | 137 +--------------------+-----------------+ 138 139 SEE ALSO 140 lgrp_home(3LGRP), liblgrp(3LIB), attributes(5) 141 142 143 144 April 16, 2003 LGRP_AFFINITY_GET(3LGRP)