lib/librt/pset.3

   1 .\"     $NetBSD: pset.3,v 1.9 2009/01/28 23:44:45 dyoung Exp $
   2 .\"
   3 .\" Copyright (c) 2008 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Mindaugas Rasiukevicius <rmind at NetBSD org>.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd January 28, 2009
  31 .Dt PSET 3
  32 .Os
  33 .Sh NAME
  34 .Nm pset_create ,
  35 .Nm pset_assign ,
  36 .Nm pset_bind ,
  37 .Nm pset_destroy
  38 .Nd processor sets
  39 .Sh SYNOPSIS
  40 .In sys/pset.h
  41 .Ft int
  42 .Fn pset_create "psetid_t *psid"
  43 .Ft int
  44 .Fn pset_assign "psetid_t psid" "cpuid_t cpuid" "psetid_t *opsid"
  45 .Ft int
  46 .Fn pset_bind "psetid_t psid" "idtype_t type" "id_t id" "psetid_t *opsid"
  47 .Ft int
  48 .Fn pset_destroy "psetid_t psid"
  49 .Sh DESCRIPTION
  50 The processor sets API provides the possibility to exclusively
  51 dedicate specific processors or groups of processors to processes
  52 or threads.
  53 After processes or threads are bound to a group of processors by
  54 the API, the group henceforth runs only those processes or threads.
  55 This section describes the functions used to control processor sets.
  56 .Ss FUNCTIONS
  57 .Bl -tag -width compact
  58 .It Fn pset_create psid
  59 Creates a processor set, and returns its ID into
  60 .Fa psid .
  61 .It Fn pset_assign psid cpu opsid
  62 Assigns the processor specified by
  63 .Fa cpuid
  64 to the processor set specified by
  65 .Fa psid .
  66 Stores the current processor set ID of the processor or
  67 .Dv PS_NONE
  68 into
  69 .Fa opsid ,
  70 if the pointer is not
  71 .Dv NULL .
  72 .Pp
  73 If
  74 .Fa psid
  75 is set to
  76 .Dv PS_QUERY ,
  77 then the current processor set ID will be returned into
  78 .Fa psid ,
  79 and no assignment will be performed.
  80 .Pp
  81 If
  82 .Fa psid
  83 is set to
  84 .Dv PS_MYID ,
  85 then the processor set ID of the calling process will be used, and
  86 .Fa psid
  87 will be ignored.
  88 .Pp
  89 If
  90 .Fa psid
  91 is set to
  92 .Dv PS_NONE ,
  93 any assignment to the processor will be cleared.
  94 .It Fn pset_bind psid type id opsid
  95 Dedicates the processor set specified by
  96 .Fa psid
  97 to the target specified by
  98 .Fa id .
  99 The current processor set ID to which the target is bound or
 100 .Dv PS_NONE
 101 will be returned in
 102 .Fa opsid ,
 103 if the pointer is not
 104 .Dv NULL .
 105 .Nx
 106 supports the following types of targets specified by
 107 .Fa type :
 108 .Bl -tag -width P_PID
 109 .It Dv P_PID
 110 Process identified by the PID.
 111 .It Dv P_LWPID
 112 Thread of the calling process indentified by the LID.
 113 .El
 114 .Pp
 115 If
 116 .Fa psid
 117 is set to
 118 .Dv PS_QUERY ,
 119 then the current processor set ID to which the target is bound or
 120 .Dv PS_NONE
 121 will be returned in
 122 .Fa opsid ,
 123 and no binding will be performed.
 124 If
 125 .Fa psid
 126 is set to
 127 .Dv PS_MYID ,
 128 then the processor set ID of the calling process will be used.
 129 .Pp
 130 If
 131 .Fa psid
 132 is set to
 133 .Dv PS_NONE ,
 134 the specified target will be unbound from the processor set.
 135 .It Fn pset_destroy psid
 136 Destroys the processor set specified by
 137 .Fa psid .
 138 Before destroying the processor set, all related assignments of the
 139 processors will be cleared, and all bound threads will be unbound.
 140 .Pp
 141 If
 142 .Fa psid
 143 is
 144 .Dv PS_MYID ,
 145 the processor set ID of the caller thread will be used.
 146 .El
 147 .Sh NOTES
 148 The
 149 .Fa pset_bind
 150 function can return the current processor set ID to which the
 151 target is bound, or
 152 .Dv PS_NONE .
 153 However, for example, the process may have many threads, which could be
 154 bound to different processor sets.
 155 In such a case it is unspecified which thread will be used to return
 156 the information.
 157 .Pp
 158 There is an alternative thread affinity interface, see
 159 .Xr affinity 3 .
 160 However, processor sets and thread affinity are mutually exclusive,
 161 hence mixing of these interfaces is prohibited.
 162 .Sh RETURN VALUES
 163 Upon successful completion these functions return 0.
 164 Otherwise, \-1 is returned and
 165 .Va errno
 166 is set to indicate the error.
 167 .Sh EXAMPLES
 168 An example of code fragment, which assigns the CPU whose ID is 0,
 169 for current process:
 170 .Bd -literal
 171         psetid_t psid;
 172         cpuid_t ci = 0;
 173
 174         if (pset_create(\*[Am]psid) \*[Lt] 0)
 175                 err(EXIT_FAILURE, "pset_create");
 176
 177         /* Assign CPU 0 to the processor-set */
 178         if (pset_assign(psid, ci, NULL) \*[Lt] 0)
 179                 err(EXIT_FAILURE, "pset_assign");
 180
 181         /* Bind the current process to the processor-set */
 182         if (pset_bind(psid, P_PID, P_MYID, NULL) \*[Lt] 0)
 183                 err(EXIT_FAILURE, "pset_bind");
 184
 185         /*
 186          * At this point, CPU 0 runs only the current process.
 187          */
 188         perform_work();
 189
 190         if (pset_destroy(psid) \*[Lt] 0)
 191                 err(EXIT_FAILURE, "pset_destroy");
 192 .Ed
 193 .Sh ERRORS
 194 The
 195 .Fn pset_create
 196 function fails if:
 197 .Bl -tag -width Er
 198 .It Bq Er ENOMEM
 199 No memory is available for creation of the processor set, or limit
 200 of the allowed count of the processor sets was reached.
 201 .It Bq Er EPERM
 202 The calling process is not the super-user.
 203 .El
 204 .Pp
 205 The
 206 .Fn pset_assign
 207 function fails if:
 208 .Bl -tag -width Er
 209 .It Bq Er EBUSY
 210 Another operation is performing on the processor set.
 211 .It Bq Er EINVAL
 212 .Fa psid
 213 or
 214 .Fa cpuid
 215 are invalid.
 216 .It Bq Er EPERM
 217 The calling process is not the super-user, and
 218 .Fa psid
 219 is not
 220 .Dv PS_QUERY .
 221 .El
 222 .Pp
 223 The
 224 .Fn pset_bind
 225 function fails if:
 226 .Bl -tag -width Er
 227 .It Bq Er EBUSY
 228 Another operation is performing on the processor set.
 229 .It Bq Er EINVAL
 230 .Fa psid
 231 or
 232 .Fa type
 233 are invalid.
 234 .It Bq Er EPERM
 235 The calling process is not the super-user, and
 236 .Fa psid
 237 is not
 238 .Dv PS_QUERY .
 239 .It Bq Er ESRCH
 240 The specified target was not found.
 241 .El
 242 .Pp
 243 The
 244 .Fn pset_destroy
 245 function fails if:
 246 .Bl -tag -width Er
 247 .It Bq Er EBUSY
 248 Another operation is performing on the processor set.
 249 .It Bq Er EPERM
 250 The calling process is not the super-user.
 251 .El
 252 .Sh SEE ALSO
 253 .Xr affinity 3 ,
 254 .Xr cpuset 3 ,
 255 .Xr sched 3 ,
 256 .Xr schedctl 8
 257 .Sh STANDARDS
 258 This API is expected to be compatible with the APIs found in Solaris and
 259 HP-UX operating systems.
 260 .Sh HISTORY
 261 The processor sets appeared in
 262 .Nx 5.0 .