1.\" $NetBSD: pset.3,v 1.10 2009/01/29 00:54:54 rmind 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 50The processor sets API provides the possibility to exclusively 51dedicate specific processors or groups of processors to processes 52or threads. 53After processes or threads are bound to a group of processors by 54the API, the group henceforth runs only those processes or threads. 55This section describes the functions used to control processor sets. 56.Ss FUNCTIONS 57.Bl -tag -width compact 58.It Fn pset_create psid 59Creates a processor set, and returns its ID into 60.Fa psid . 61.It Fn pset_assign psid cpu opsid 62Assigns the processor specified by 63.Fa cpuid 64to the processor set specified by 65.Fa psid . 66Stores the current processor set ID of the processor or 67.Dv PS_NONE 68into 69.Fa opsid , 70if the pointer is not 71.Dv NULL . 72.Pp 73If 74.Fa psid 75is set to 76.Dv PS_QUERY , 77then the current processor set ID will be returned into 78.Fa psid , 79and no assignment will be performed. 80.Pp 81If 82.Fa psid 83is set to 84.Dv PS_MYID , 85then the processor set ID of the calling process will be used, and 86.Fa psid 87will be ignored. 88.Pp 89If 90.Fa psid 91is set to 92.Dv PS_NONE , 93any assignment to the processor will be cleared. 94.It Fn pset_bind psid type id opsid 95Dedicates the processor set specified by 96.Fa psid 97to the target specified by 98.Fa id . 99The current processor set ID to which the target is bound or 100.Dv PS_NONE 101will be returned in 102.Fa opsid , 103if the pointer is not 104.Dv NULL . 105.Nx 106supports the following types of targets specified by 107.Fa type : 108.Bl -tag -width P_PID 109.It Dv P_PID 110Process identified by the PID. 111.It Dv P_LWPID 112Thread of the calling process indentified by the LID. 113.El 114.Pp 115If 116.Fa psid 117is set to 118.Dv PS_QUERY , 119then the current processor set ID to which the target is bound or 120.Dv PS_NONE 121will be returned in 122.Fa opsid , 123and no binding will be performed. 124If 125.Fa psid 126is set to 127.Dv PS_MYID , 128then the processor set ID of the calling process will be used. 129.Pp 130If 131.Fa psid 132is set to 133.Dv PS_NONE , 134the specified target will be unbound from the processor set. 135.It Fn pset_destroy psid 136Destroys the processor set specified by 137.Fa psid . 138Before destroying the processor set, all related assignments of the 139processors will be cleared, and all bound threads will be unbound. 140.Pp 141If 142.Fa psid 143is 144.Dv PS_MYID , 145the processor set ID of the caller thread will be used. 146.El 147.Sh NOTES 148The 149.Fa pset_bind 150function can return the current processor set ID to which the 151target is bound, or 152.Dv PS_NONE . 153However, for example, the process may have many threads, which could be 154bound to different processor sets. 155In such a case it is unspecified which thread will be used to return 156the information. 157.Pp 158There is an alternative thread affinity interface, see 159.Xr affinity 3 . 160However, processor sets and thread affinity are mutually exclusive, 161hence mixing of these interfaces is prohibited. 162.Sh RETURN VALUES 163Upon successful completion these functions return 0. 164Otherwise, \-1 is returned and 165.Va errno 166is set to indicate the error. 167.Sh EXAMPLES 168An example of code fragment, which assigns the CPU whose ID is 0, 169for 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 194The 195.Fn pset_create 196function fails if: 197.Bl -tag -width Er 198.It Bq Er ENOMEM 199No memory is available for creation of the processor set, or limit 200of the allowed count of the processor sets was reached. 201.It Bq Er EPERM 202The calling process is not the super-user. 203.El 204.Pp 205The 206.Fn pset_assign 207function fails if: 208.Bl -tag -width Er 209.It Bq Er EBUSY 210Another operation is performing on the processor set. 211.It Bq Er EINVAL 212.Fa psid 213or 214.Fa cpuid 215are invalid. 216.It Bq Er EPERM 217The calling process is not the super-user, and 218.Fa psid 219is not 220.Dv PS_QUERY . 221.El 222.Pp 223The 224.Fn pset_bind 225function fails if: 226.Bl -tag -width Er 227.It Bq Er EBUSY 228Another operation is performing on the processor set. 229.It Bq Er EINVAL 230.Fa psid 231or 232.Fa type 233are invalid. 234.It Bq Er EPERM 235The calling process is not the super-user, and 236.Fa psid 237is not 238.Dv PS_QUERY . 239.It Bq Er ESRCH 240The specified target was not found. 241.El 242.Pp 243The 244.Fn pset_destroy 245function fails if: 246.Bl -tag -width Er 247.It Bq Er EBUSY 248Another operation is performing on the processor set. 249.It Bq Er EPERM 250The 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 258This API is expected to be compatible with the APIs found in Solaris and 259HP-UX operating systems. 260.Sh HISTORY 261The processor sets appeared in 262.Nx 5.0 . 263