NetBSD/lib/librt/pset.3

.\"	$NetBSD: pset.3,v 1.13 2017/07/03 21:32:51 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 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 indentified 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 .