1lgrp_affinity_get(3LGRP)Locality Group Library Functionslgrp_affinity_get(3LGRP)
2
3
4

NAME

6       lgrp_affinity_get, lgrp_affinity_set - get of set lgroup affinity
7

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

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 affini‐
43       ties.
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 particuliar lgroup.  The levels of affinity are  the  fol‐
62       lowing 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 reconfigu‐
74       ration, processor offlining, processor binding, and processor set bind‐
75       ing and manipulation are examples of events that can cause the  operat‐
76       ing system to change the thread's home lgroup for which it has a strong
77       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 particuliar 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

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

ERRORS

108       The lgrp_affinity_get() and lgrp_affinity_set() functions will fail if:
109
110       EINVAL    The specified lgroup, affinity, or ID type is not valid.
111
112
113       EPERM     The  effective  user  of  the  calling  process does not have
114                 appropriate privileges, and its real  or  effective  user  ID
115                 does  not  match  the real or effective user ID of one of the
116                 LWPs.
117
118
119       ESRCH     The specified lgroup or LWP(s) was not found.
120
121

ATTRIBUTES

123       See attributes(5) for descriptions of the following attributes:
124
125
126
127
128       ┌─────────────────────────────┬─────────────────────────────┐
129       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
130       ├─────────────────────────────┼─────────────────────────────┤
131       │Interface Stability          │Evolving                     │
132       ├─────────────────────────────┼─────────────────────────────┤
133       │MT-Level                     │MT-Safe                      │
134       └─────────────────────────────┴─────────────────────────────┘
135

SEE ALSO

137       lgrp_home(3LGRP), liblgrp(3LIB), attributes(5)
138
139
140
141SunOS 5.11                        16 Apr 2003         lgrp_affinity_get(3LGRP)
Impressum