summaryrefslogtreecommitdiff
path: root/lib/libpthread
diff options
context:
space:
mode:
authorrmind <rmind@NetBSD.org>2008-06-16 14:25:49 +0000
committerrmind <rmind@NetBSD.org>2008-06-16 14:25:49 +0000
commite6acd90e07a5a12d90f42c2b6d08f6acc00c8d68 (patch)
treee6f1436813a686449fd3e82567b92da532e6a6a0 /lib/libpthread
parentddbb9c58dd228161b4e78088e515af2280bcd27d (diff)
- Add affinity(3) manual page, which describes thread affinity,
pthread_setaffinity_np(3) and pthread_getaffinity_np(3) functions, provides simple code example. - Add cpuset(3) manual page, which describes API of CPU-sets. Thanks <wiz> for many improvements!
Diffstat (limited to 'lib/libpthread')
-rw-r--r--lib/libpthread/Makefile6
-rw-r--r--lib/libpthread/affinity.3125
2 files changed, 129 insertions, 2 deletions
diff --git a/lib/libpthread/Makefile b/lib/libpthread/Makefile
index b0beb83168b..1f025fac998 100644
--- a/lib/libpthread/Makefile
+++ b/lib/libpthread/Makefile
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.51 2008/03/10 14:47:06 rmind Exp $
+# $NetBSD: Makefile,v 1.52 2008/06/16 14:25:49 rmind Exp $
#
WARNS= 4
@@ -91,7 +91,7 @@ _context_u.po: _context_u.o
${_MKTARGET_CREATE}
cp _context_u.o _context_u.po
-MAN+= pthread.3 \
+MAN+= affinity.3 pthread.3 \
pthread_attr.3 \
pthread_attr_getname_np.3 \
pthread_attr_setcreatesuspend_np.3 \
@@ -117,6 +117,8 @@ MAN+= pthread.3 \
pthread_spin_init.3 pthread_spin_lock.3 pthread_spin_unlock.3 \
pthread_suspend_np.3 pthread_testcancel.3
+MLINKS+= affinity.3 pthread_setaffinity_np.3
+MLINKS+= affinity.3 pthread_getaffinity_np.3
MLINKS+= pthread_attr.3 pthread_attr_init.3
MLINKS+= pthread_attr.3 pthread_attr_destroy.3
MLINKS+= pthread_attr.3 pthread_attr_setdetachstate.3
diff --git a/lib/libpthread/affinity.3 b/lib/libpthread/affinity.3
new file mode 100644
index 00000000000..80650ce2760
--- /dev/null
+++ b/lib/libpthread/affinity.3
@@ -0,0 +1,125 @@
+.\" $NetBSD: affinity.3,v 1.1 2008/06/16 14:25:49 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 June 15, 2008
+.Dt AFFINITY 3
+.Os
+.Sh NAME
+.Nm pthread_setaffinity_np ,
+.Nm pthread_getaffinity_np
+.Nd affinity of threads
+.Sh LIBRARY
+.Lb libpthread
+.Sh SYNOPSIS
+.In pthread.h
+.In sched.h
+.Ft int
+.Fn pthread_setaffinity_np "pthread_t thread" "size_t size" "cpuset_t *set"
+.Ft int
+.Fn pthread_getaffinity_np "pthread_t thread" "size_t size" "cpuset_t *set"
+.Sh DESCRIPTION
+Thread affinity allows to run the thread on specified CPU or CPUs only.
+.Pp
+.Fn pthread_setaffinity_np
+function sets the affinity mask
+.Fa set
+for
+.Fa thread .
+At least one valid CPU must be set in the mask.
+.Pp
+The
+.Fn pthread_getaffinity_np
+function gets the affinity mask of
+.Fa thread
+into
+.Fa set .
+.Pp
+.Fa set
+must be created and initialized using the
+.Xr cpuset 3
+functions.
+.Sh RETURN VALUES
+The
+.Fn pthread_setaffinity_np
+and
+.Fn pthread_getaffinity_np
+functions return 0 on success.
+Otherwise, an error number is returned to indicate the error.
+.Sh EXAMPLES
+An example of code fragment, which sets the affinity for the current
+thread to the CPU whose ID is 0:
+.Bd -literal
+ cpuset_t *cset;
+ pthread_t pth;
+ cpuid_t ci;
+
+ cset = cpuset_create();
+ if (cset == NULL) {
+ err(EXIT_FAILURE, "cpuset_create");
+ }
+ ci = 0;
+ cpuset_set(ci);
+
+ pth = pthread_self();
+ error = pthread_setaffinity_np(pth, cpuset_size(cset), cset);
+ if (error) {
+ ...
+ }
+ cpuset_destroy(cset);
+.Ed
+.Sh ERRORS
+The
+.Fn pthread_setaffinity_np
+and
+.Fn pthread_getaffinity_np
+functions fail if:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The specified
+.Fa set
+was invalid.
+.It Bq Er EPERM
+The calling process lacks the appropriate privileges to perform
+the operation.
+.It Bq Er ESRCH
+No thread could be found corresponding to the one specified by
+.Fa thread .
+.El
+.Sh NOTES
+Thread affinity might be used together with the processor sets, see
+.Xr pset 3 .
+In such case, the affinity mask takes precedence over the assignment
+to processor sets.
+.Sh SEE ALSO
+.Xr cpuset 3 ,
+.Xr pset 3 ,
+.Xr pthread_getschedparam 3 ,
+.Xr pthread_setschedparam 3 ,
+.Xr sched 3 ,
+.Xr schedctl 8