\"      $NetBSD: pset.3,v 1.15 2025/02/21 15:33:58 wiz 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 February 21, 2025
Dt PSET 3
Os
Sh NAME
Nm pset_create ,
Nm pset_assign ,
Nm pset_bind ,
Nm pset_destroy
Nd processor sets
Sh LIBRARY
Lb librt
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
Except for
Dv PS_QUERY
operations, these interfaces require super-user privileges.
Pp
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 .

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.