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