263 lines
6.7 KiB
Groff
263 lines
6.7 KiB
Groff
.\" $NetBSD: pset.3,v 1.10 2009/01/29 00:54:54 rmind 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 January 28, 2009
|
|
.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.
|
|
.Ss 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
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
If
|
|
.Fa psid
|
|
is set to
|
|
.Dv PS_NONE ,
|
|
any assignment to the processor will be cleared.
|
|
.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_PID
|
|
.It Dv P_PID
|
|
Process identified by the PID.
|
|
.It Dv P_LWPID
|
|
Thread of the calling process indentified by the LID.
|
|
.El
|
|
.Pp
|
|
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.
|
|
If
|
|
.Fa psid
|
|
is set to
|
|
.Dv PS_MYID ,
|
|
then the processor set ID of the calling process will be used.
|
|
.Pp
|
|
If
|
|
.Fa psid
|
|
is set to
|
|
.Dv PS_NONE ,
|
|
the specified target will be unbound from the processor set.
|
|
.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 NOTES
|
|
The
|
|
.Fa 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(\*[Am]psid) \*[Lt] 0)
|
|
err(EXIT_FAILURE, "pset_create");
|
|
|
|
/* Assign CPU 0 to the processor-set */
|
|
if (pset_assign(psid, ci, NULL) \*[Lt] 0)
|
|
err(EXIT_FAILURE, "pset_assign");
|
|
|
|
/* Bind the current process to the processor-set */
|
|
if (pset_bind(psid, P_PID, P_MYID, NULL) \*[Lt] 0)
|
|
err(EXIT_FAILURE, "pset_bind");
|
|
|
|
/*
|
|
* At this point, CPU 0 runs only the current process.
|
|
*/
|
|
perform_work();
|
|
|
|
if (pset_destroy(psid) \*[Lt] 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 .
|