aboutsummaryrefslogtreecommitdiff
path: root/pthreads/manual/sched_setaffinity.html
blob: ec7ef7e0ec0e50fed19e4ffe5b3330bb4e3ffee6 (plain)
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
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
	<TITLE>PTHREAD_CREATE(3) manual page</TITLE>
	<META NAME="GENERATOR" CONTENT="OpenOffice.org 3.4  (Win32)">
	<META NAME="CREATED" CONTENT="20050504;19394700">
	<META NAME="CHANGED" CONTENT="20120921;10513422">
	<STYLE TYPE="text/css">
	<!--
		H4.cjk { font-family: "SimSun" }
		H4.ctl { font-family: "Mangal" }
		H2.cjk { font-family: "SimSun" }
		H2.ctl { font-family: "Mangal" }
	-->
	</STYLE>
</HEAD>
<BODY LANG="en-GB" BGCOLOR="#ffffff" DIR="LTR">
<H4 CLASS="western"><FONT FACE="Times New Roman, serif"><FONT SIZE=3><SPAN STYLE="font-style: normal">POSIX
Threads for Windows &ndash; REFERENCE - <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A></SPAN></FONT></FONT></H4>
<P><A HREF="index.html">Reference Index</A></P>
<P><A HREF="#toc">Table of Contents</A></P>
<H2 CLASS="western"><A HREF="#toc0" NAME="sect0">Name</A></H2>
<P>sched_setaffinity - set process CPU affinity</P>
<P>sched_getaffinity - get process CPU affinity</P>
<H2 CLASS="western"><A HREF="#toc1" NAME="sect1">Synopsis</A></H2>
<P><B>#include &lt;sched.h&gt; </B>
</P>
<P><B>int sched_setaffinity(pid_t </B><I><SPAN STYLE="font-weight: normal">pid</SPAN></I><B>,
int </B><I><SPAN STYLE="font-weight: normal">cpusetsize</SPAN></I><B>,
const cpu_set_t *</B><I><SPAN STYLE="font-weight: normal">mask</SPAN></I><B>);</B></P>
<P><B>int sched_getaffinity(pid_t </B><I><SPAN STYLE="font-weight: normal">pid</SPAN></I><B>,
int </B><I><SPAN STYLE="font-weight: normal">cpusetsize</SPAN></I><B>,
cpu_set_t *</B><I><SPAN STYLE="font-weight: normal">mask</SPAN></I><B>);</B></P>
<H2 CLASS="western"><A HREF="#toc2" NAME="sect2">Description</A></H2>
<P><B>sched_setaffinity</B> sets the CPU affinity mask of the process
whose ID is <I>pid</I> to the value specified by mask. If <I>pid</I>
is zero, then the calling process is used. The argument <I>cpusetsize</I>
is the length (in bytes) of the data pointed to by <I>mask</I>.
Normally this argument would be specified as <I>sizeof(cpu_set_t)</I>.</P>
<P>If the process specified by <I>pid</I> is not currently running on
one of the CPUs specified in <I>mask</I>, then that process is
migrated to one of the CPUs specified in <I>mask</I>.</P>
<P>After a call to <B>sched_setaffinity</B>, the set of CPUs on which
the process will actually run is the intersection of the set
specified in the <I>mask</I> argument and the set of CPUs actually
present on the system.</P>
<P><B>sched_getaffinity</B> writes the affinity mask of the process
whose ID is <I>pid</I> into the cpu_set_t structure pointed to by
<I>mask</I>. The <I>cpusetsize</I> argument specifies the size (in
bytes) of <I>mask</I>. If <I>pid</I> is zero, then the mask of the
calling process is returned.</P>
<P><B>Pthreads-w32</B> currently ignores the <I>cpusetsize</I>
parameter for either function because cpu_set_t is a direct typeset
to the Windows affinity vector type DWORD_PTR.</P>
<P>Windows may require that the requesting process have permission to
set its own CPU affinity or that of another process.</P>
<H2 CLASS="western"><A HREF="#toc3" NAME="sect3">Return Value</A></H2>
<P>On success, <B>sched_setaffinity</B> and <B>sched_getaffinity</B>
return 0. On error, -1 is returned, and <I>errno</I> is set
appropriately.</P>
<H2 CLASS="western"><A HREF="#toc4" NAME="sect4">Errors</A></H2>
<DL>
	<DT><B>EFAULT</B></DT><DL>
		<DL>
			<DT STYLE="margin-left: 0.02cm">
			A supplied memory address was invalid.</DT></DL>
	</DL>
	<DT>
	<B>EINVAL</B></DT><DL>
		<DL>
			<DT STYLE="margin-left: 0.04cm">
			The affinity bit mask mask contains no processors that are
			currently physically on the system.</DT></DL>
	</DL>
	<DT>
	<B>EAGAIN</B></DT><DL>
		<DL>
			<DT STYLE="margin-left: 0.02cm">
			The function did not succeed in changing or obtaining the CPU
			affinity for some undetermined reason. Try again.</DT></DL>
	</DL>
	<DT>
	<B>EPERM</B></DT><DL>
		<DL>
			<DT STYLE="margin-left: 0.02cm">
			The calling process does not have appropriate privileges.</DT></DL>
	</DL>
	<DT>
	<B>ESRCH</B> 
	</DT><DL>
		<DL>
			<DT STYLE="margin-left: 0.02cm">
			The process whose ID is pid could not be found.</DT></DL>
	</DL>
</DL>
<H2 CLASS="western">
<A HREF="#toc5" NAME="sect5">Application Usage</A></H2>
<P>A process's CPU affinity mask determines the set of CPUs on which
it is eligible to run. On a multiprocessor system, setting the CPU
affinity mask can be used to obtain performance benefits. For
example, by dedicating one CPU to a particular process (i.e., setting
the affinity mask of that process to specify a single CPU, and
setting the affinity mask of all other processes to exclude that
CPU), it is possible to ensure maximum execution speed for that
process. Restricting a process to run on a single CPU also avoids the
performance cost caused by the cache invalidation that occurs when a
process ceases to execute on one CPU and then recommences execution
on a different CPU.</P>
<P>A CPU affinity mask is represented by the cpu_set_t structure, a
&quot;CPU set&quot;, pointed to by <I>mask</I>. A set of macros for
manipulating CPU sets is described in <B>cpu_set</B>(3).</P>
<H2 CLASS="western"><A HREF="#toc6" NAME="sect6">See Also</A></H2>
<P><A HREF="cpu_set.html"><B>cpu_set</B>(3)</A>,
<A HREF="pthread_setaffinity_np.html"><B>pthread_setaffininty_np</B>(3)</A>,
<A HREF="pthread_setaffinity_np.html"><B>pthread_getaffinity_np</B>(3)</A></P>
<H2 CLASS="western"><A HREF="#toc7" NAME="sect7">Copyright</A></H2>
<P>Most of this is taken from the Linux manual page.</P>
<P>Modified by Ross Johnson for use with <B>Pthreads-w32</B>.</P>
<HR>
<P><A NAME="toc"></A><B>Table of Contents</B></P>
<UL>
	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect0" NAME="toc0">Name</A>
		</P>
	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect1" NAME="toc1">Synopsis</A>
		</P>
	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect2" NAME="toc2">Description</A>
		</P>
	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect3" NAME="toc3">Return
	Value</A> 
	</P>
	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect4" NAME="toc4">Errors</A>
		</P>
	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect5" NAME="toc5">Application
	Usage</A></P>
	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect6" NAME="toc6">See
	Also</A></P>
	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect7" NAME="toc7">Copyright</A></P>
</UL>
<H4 CLASS="western"><BR><BR>
</H4>
</BODY>
</HTML>