1.\" $NetBSD: pset.3,v 1.14 2022/05/31 08:43:14 andvar 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 May 6, 2010 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.Sh 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 73The following actions can be specified: 74.Bl -enum -offset 2n 75.It 76If 77.Fa psid 78is set to 79.Dv PS_QUERY , 80then the current processor set ID will be returned into 81.Fa psid , 82and no assignment will be performed. 83.It 84If 85.Fa psid 86is set to 87.Dv PS_MYID , 88then the processor set ID of the calling process will be used, and 89.Fa psid 90will be ignored. 91.It 92If 93.Fa psid 94is set to 95.Dv PS_NONE , 96any assignment to the processor will be cleared. 97.El 98.It Fn pset_bind psid type id opsid 99Dedicates the processor set specified by 100.Fa psid 101to the target specified by 102.Fa id . 103The current processor set ID to which the target is bound or 104.Dv PS_NONE 105will be returned in 106.Fa opsid , 107if the pointer is not 108.Dv NULL . 109.Nx 110supports the following types of targets specified by 111.Fa type : 112.Bl -tag -width P_LWPID -offset 2n 113.It Dv P_PID 114Process identified by the PID. 115.It Dv P_LWPID 116Thread of the calling process identified by the LID. 117.El 118.Pp 119The following actions can be specified: 120.Bl -enum -offset 2n 121.It 122If 123.Fa psid 124is set to 125.Dv PS_QUERY , 126then the current processor set ID to which the target is bound or 127.Dv PS_NONE 128will be returned in 129.Fa opsid , 130and no binding will be performed. 131.It 132If 133.Fa psid 134is set to 135.Dv PS_MYID , 136then the processor set ID of the calling process will be used. 137.It 138If 139.Fa psid 140is set to 141.Dv PS_NONE , 142the specified target will be unbound from the processor set. 143.El 144.It Fn pset_destroy psid 145Destroys the processor set specified by 146.Fa psid . 147Before destroying the processor set, all related assignments of the 148processors will be cleared, and all bound threads will be unbound. 149.Pp 150If 151.Fa psid 152is 153.Dv PS_MYID , 154the processor set ID of the caller thread will be used. 155.El 156.Sh IMPLEMENTATION NOTES 157The 158.Fn pset_bind 159function can return the current processor set ID to which the 160target is bound, or 161.Dv PS_NONE . 162However, for example, the process may have many threads, which could be 163bound to different processor sets. 164In such a case it is unspecified which thread will be used to return 165the information. 166.Pp 167There is an alternative thread affinity interface, see 168.Xr affinity 3 . 169However, processor sets and thread affinity are mutually exclusive, 170hence mixing of these interfaces is prohibited. 171.Sh RETURN VALUES 172Upon successful completion these functions return 0. 173Otherwise, \-1 is returned and 174.Va errno 175is set to indicate the error. 176.Sh EXAMPLES 177An example of code fragment, which assigns the CPU whose ID is 0, 178for current process: 179.Bd -literal 180 psetid_t psid; 181 cpuid_t ci = 0; 182 183 if (pset_create(&psid) < 0) 184 err(EXIT_FAILURE, "pset_create"); 185 186 /* Assign CPU 0 to the processor-set */ 187 if (pset_assign(psid, ci, NULL) < 0) 188 err(EXIT_FAILURE, "pset_assign"); 189 190 /* Bind the current process to the processor-set */ 191 if (pset_bind(psid, P_PID, P_MYID, NULL) < 0) 192 err(EXIT_FAILURE, "pset_bind"); 193 194 /* 195 * At this point, CPU 0 runs only the current process. 196 */ 197 perform_work(); 198 199 if (pset_destroy(psid) < 0) 200 err(EXIT_FAILURE, "pset_destroy"); 201.Ed 202.Sh ERRORS 203The 204.Fn pset_create 205function fails if: 206.Bl -tag -width Er 207.It Bq Er ENOMEM 208No memory is available for creation of the processor set, or limit 209of the allowed count of the processor sets was reached. 210.It Bq Er EPERM 211The calling process is not the super-user. 212.El 213.Pp 214The 215.Fn pset_assign 216function fails if: 217.Bl -tag -width Er 218.It Bq Er EBUSY 219Another operation is performing on the processor set. 220.It Bq Er EINVAL 221.Fa psid 222or 223.Fa cpuid 224are invalid. 225.It Bq Er EPERM 226The calling process is not the super-user, and 227.Fa psid 228is not 229.Dv PS_QUERY . 230.El 231.Pp 232The 233.Fn pset_bind 234function fails if: 235.Bl -tag -width Er 236.It Bq Er EBUSY 237Another operation is performing on the processor set. 238.It Bq Er EINVAL 239.Fa psid 240or 241.Fa type 242are invalid. 243.It Bq Er EPERM 244The calling process is not the super-user, and 245.Fa psid 246is not 247.Dv PS_QUERY . 248.It Bq Er ESRCH 249The specified target was not found. 250.El 251.Pp 252The 253.Fn pset_destroy 254function fails if: 255.Bl -tag -width Er 256.It Bq Er EBUSY 257Another operation is performing on the processor set. 258.It Bq Er EPERM 259The calling process is not the super-user. 260.El 261.Sh SEE ALSO 262.Xr affinity 3 , 263.Xr cpuset 3 , 264.Xr sched 3 , 265.Xr schedctl 8 266.Sh STANDARDS 267This API is expected to be compatible with the APIs found in Solaris and 268HP-UX operating systems. 269.Sh HISTORY 270The processor sets appeared in 271.Nx 5.0 . 272