Locality Group Library Functions         lgrpaffinityget(3LGRP)



NAME
     lgrpaffinityget, lgrpaffinityset -  get  of  set  lgroup
     affinity

SYNOPSIS
     cc [ flag ... ] file... -llgrp [ library ... ]
     #include 

     lgrpaffinityt lgrpaffinityget(idtypet idtype, idt id,
          lgrpidt lgrp);


     int lgrpaffinityset(idtypet idtype, idt id, lgrpidt lgrp,
          lgrpaffinityt affinity);


DESCRIPTION
     The lgrpaffinityget() function returns the  affinity  that
     the  LWP or set of LWPs specified by the idtype and id argu-
     ments have for the given lgroup.


     The lgrpaffinityset() function sets the affinity that  the
     LWP  or  set of LWPs specified by idtype and id have for the
     given  lgroup.   The  lgroup  affinity   can   be   set   to
     LGRPAFSTRONG, LGRPAFWEAK, or LGRPAFNONE.


     If the idtype is PID, the affinity is retrieved for one of
     the  LWPs in the process or set for all the LWPs of the pro-
     cess with process ID (PID) id. The affinity is retrieved  or
     set  for  the  LWP  of the current process with LWP ID id if
     idtype is PLWPID.  If id is PMYID, then the current LWP or
     process is specified.


     The operating system uses the lgroup affinities as advice on
     where  to  run  a thread and allocate its memory and factors
     this advice in with other  constraints.   Processor  binding
     and  processor  sets can restrict which lgroups a thread can
     run on, but do not change the lgroup affinities.


     Each thread can have an affinity for an lgroup in the system
     such  that  the  thread  will tend to be scheduled to run on
     that lgroup and allocate memory from there  whenever  possi-
     ble.   If  the thread has affinity for more than one lgroup,
     the operating system will try to run the thread and allocate
     its  memory  on  the  lgroup  for which it has the strongest
     affinity, then the next strongest, and so on up through some
     small,  system-dependent  number of these lgroup affinities.
     When multiple lgroups have the same affinity, the  order  of



SunOS 5.11          Last change: 16 Apr 2003                    1






Locality Group Library Functions         lgrpaffinityget(3LGRP)



     preference among them is unspecified and up to the operating
     system to choose.  The lgroup with  the  strongest  affinity
     that  the  thread  can  run on is known as its "home lgroup"
     (see lgrphome(3LGRP)) and is usually the operating system's
     first  choice  of  where  to run the thread and allocate its
     memory.


      There are different levels of affinity that can  be  speci-
     fied  by  a  thread for a particuliar lgroup.  The levels of
     affinity are the following from strongest to weakest:

       LGRPAFSTRONG         /* strong affinity */
       LGRPAFWEAK           /* weak affinity */
       LGRPAFNONE           /* no affinity */



     The LGRPAFSTRONG affinity serves as a hint to the operat-
     ing system that the calling thread has a strong affinity for
     the given lgroup.  If this is the thread's home lgroup,  the
     operating system will avoid rehoming it to another lgroup if
     possible.  However, dynamic reconfiguration, processor  off-
     lining,  processor  binding,  and  processor set binding and
     manipulation are examples  of  events  that  can  cause  the
     operating  system  to  change  the  thread's home lgroup for
     which it has a strong affinity.


     The LGRPAFWEAK affinity is a hint to the operating system
     that  the  calling  thread has a weak affinity for the given
     lgroup.  If a thread  has  a  weak  affinity  for  its  home
     lgroup,  the  operating  system  interpets this to mean that
     thread  does  not  mind  whether  it  is   rehomed,   unlike
     LGRPAFSTRONG.   Load  balancing, dynamic reconfiguration,
     processor binding, or processor set binding and manipulation
     are  examples  of events that can cause the operating system
     to change a thread's home lgroup for which  it  has  a  weak
     affinity.


     The LGRPAFNONE affinity signifies no affinity and can  be
     used to remove a thread's affinity for a particuliar lgroup.
     Initially, each thread has no affinity to any lgroup.  If  a
     thread  has  no  lgroup affinities set, the operating system
     chooses a home lgroup for the thread with no affinity set.

RETURN VALUES
     Upon successful completion, lgrpaffinityget() returns  the
     affinity for the given lgroup.





SunOS 5.11          Last change: 16 Apr 2003                    2






Locality Group Library Functions         lgrpaffinityget(3LGRP)



     Upon successful completion, lgrpaffinityset() return 0.


     Otherwise, both functions return -1 and set errno  to  indi-
     cate the error.

ERORS
     The lgrpaffinityget()  and  lgrpaffinityset()  functions
     will fail if:

     EINVAL    The specified lgroup, affinity, or ID type is  not
               valid.


     EPERM     The effective user of the calling process does not
               have  appropriate  privileges,  and  its  real  or
               effective user ID  does  not  match  the  real  or
               effective user ID of one of the LWPs.


     ESRCH     The specified lgroup or LWP(s) was not found.


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Evolving                    
    
     MT-Level                     MT-Safe                     
    


SEE ALSO
     lgrphome(3LGRP), liblgrp(3LIB), attributes(5)















SunOS 5.11          Last change: 16 Apr 2003                    3