aboutsummaryrefslogtreecommitdiff
path: root/manual/resource.texi
diff options
context:
space:
mode:
authorUlrich Drepper <drepper@redhat.com>2003-05-10 08:39:58 +0000
committerUlrich Drepper <drepper@redhat.com>2003-05-10 08:39:58 +0000
commitd9997a45eeba745384e3591978186debd5883be7 (patch)
tree9a204e82d9dbdc451984f5e8e1801cf49940394d /manual/resource.texi
parentd067c97eb5c0d019608c51310d8f1bafecd77513 (diff)
downloadglibc-d9997a45eeba745384e3591978186debd5883be7.zip
glibc-d9997a45eeba745384e3591978186debd5883be7.tar.gz
glibc-d9997a45eeba745384e3591978186debd5883be7.tar.bz2
Update.
2003-05-09 Thorsten Kukuk <kukuk@suse.de> * sysdeps/unix/sysv/linux/netinet/igmp.h: Don't include kernel headers, add defines from kernel header, move it from here... * inet/netinet/igmp.h: ... to here. * inet/Makefile (headers): Add netinet/igmp.h. * sysdeps/unix/sysv/linux/Makefile: Remove netinet/igmp.h. * sysdeps/unix/sysv/linux/Dist: Remove netinet/igmp.h. 2003-05-10 Ulrich Drepper <drepper@redhat.com> * sysdeps/pthread/lio_listio64.c (lio_listio64): If SIG == NULL, use dummy sigevent structure with SIGEV_NONE [PR libc/5015]. 2003-05-09 Thorsten Kukuk <kukuk@suse.de> * libio/bits/stdio.h: Sync prototypes with libio/stdio.h (remove __THROW from possible cancellation points).
Diffstat (limited to 'manual/resource.texi')
-rw-r--r--manual/resource.texi175
1 files changed, 175 insertions, 0 deletions
diff --git a/manual/resource.texi b/manual/resource.texi
index 9d2e17b..0c394f2 100644
--- a/manual/resource.texi
+++ b/manual/resource.texi
@@ -558,6 +558,7 @@ POSIX syntax had in mind.
* Realtime Scheduling:: Scheduling among the process nobility
* Basic Scheduling Functions:: Get/set scheduling policy, priority
* Traditional Scheduling:: Scheduling among the vulgar masses
+* CPU Affinity:: Limiting execution to certain CPUs
@end menu
@@ -1246,6 +1247,180 @@ nice (int increment)
@end smallexample
@end deftypefun
+
+@node CPU Affinity
+@subsection Limiting execution to certain CPUs
+
+On a multi-processor system the operating system usually distributes
+the different processes which are runnable on all available CPUs in a
+way which allows the system to work most efficiently. Which processes
+and threads run can be to some extend be control with the scheduling
+functionality described in the last sections. But which CPU finally
+executes which process or thread is not covered.
+
+There are a number of reasons why a program might want to have control
+over this aspect of the system as well:
+
+@itemize @bullet
+@item
+One thread or process is responsible for absolutely critical work
+which under no circumstances must be interrupted or hindered from
+making process by other process or threads using CPU resources. In
+this case the special process would be confined to a CPU which no
+other process or thread is allowed to use.
+
+@item
+The access to certain resources (RAM, I/O ports) has different costs
+from different CPUs. This is the case in NUMA (Non-Uniform Memory
+Architecture) machines. Preferrably memory should be accessed locally
+but this requirement is usually not visible to the scheduler.
+Therefore forcing a process or thread to the CPUs which have local
+access to the mostly used memory helps to significantly boost the
+performance.
+
+@item
+In controlled runtimes resource allocation and book-keeping work (for
+instance garbage collection) is performance local to processors. This
+can help to reduce locking costs if the resources do not have to be
+protected from concurrent accesses from different processors.
+@end itemize
+
+The POSIX standard up to this date is of not much help to solve this
+problem. The Linux kernel provides a set of interfaces to allow
+specifying @emph{affinity sets} for a process. The scheduler will
+schedule the thread or process on on CPUs specified by the affinity
+masks. The interfaces which the GNU C library define follow to some
+extend the Linux kernel interface.
+
+@comment sched.h
+@comment GNU
+@deftp {Data Type} cpu_set_t
+This data set is a bitset where each bit represents a CPU. How the
+system's CPUs are mapped to bits in the bitset is system dependent.
+The data type has a fixed size; in the unlikely case that the number
+of bits are not sufficient to describe the CPUs of the system a
+different interface has to be used.
+
+This type is a GNU extension and is defined in @file{sched.h}.
+@end deftp
+
+To manipulate the bitset, to set and reset bits, a number of macros is
+defined. Some of the macros take a CPU number as a parameter. Here
+it is important to never exceed the size of the bitset. The following
+macro specifies the number of bits in the @code{cpu_set_t} bitset.
+
+@comment sched.h
+@comment GNU
+@deftypevr Macro int CPU_SETSIZE
+The value of this macro is the maximum number of CPUs which can be
+handled with a @code{cpu_set_t} object.
+@end deftypevr
+
+The type @code{cpu_set_t} should be considered opaque; all
+manipulation should happen via the next four macros.
+
+@comment sched.h
+@comment GNU
+@deftypefn Macro void CPU_ZERO (cpu_set_t *@var{set})
+This macro initializes the CPU set @var{set} to be the empty set.
+
+This macro is a GNU extension and is defined in @file{sched.h}.
+@end deftypefn
+
+@comment sched.h
+@comment GNU
+@deftypefn Macro void CPU_SET (int @var{cpu}, cpu_set_t *@var{set})
+This macro adds @var{cpu} to the CPU set @var{set}.
+
+The @var{cpu} parameter must not have side effects since it is
+evaluated more than once.
+
+This macro is a GNU extension and is defined in @file{sched.h}.
+@end deftypefn
+
+@comment sched.h
+@comment GNU
+@deftypefn Macro void CPU_CLR (int @var{cpu}, cpu_set_t *@var{set})
+This macro removes @var{cpu} from the CPU set @var{set}.
+
+The @var{cpu} parameter must not have side effects since it is
+evaluated more than once.
+
+This macro is a GNU extension and is defined in @file{sched.h}.
+@end deftypefn
+
+@comment sched.h
+@comment GNU
+@deftypefn Macro int CPU_ISSET (int @var{cpu}, const cpu_set_t *@var{set})
+This macro returns a nonzero value (true) if @var{cpu} is a member
+of the CPU set @var{set}, and zero (false) otherwise.
+
+The @var{cpu} parameter must not have side effects since it is
+evaluated more than once.
+
+This macro is a GNU extension and is defined in @file{sched.h}.
+@end deftypefn
+
+
+CPU bitsets can be constructed from scratch or the currently installed
+affinity mask can be retrieved from the system.
+
+@comment sched.h
+@comment GNU
+@deftypefun int sched_getaffinity (pid_t @var{pid}, cpu_set_t *@var{cpuset})
+
+This functions stores the CPU affinity mask for the process or thread
+with the ID @var{pid} in the memory pointed to by @var{cpuset}. If
+successful, the function always initializes all bits in the
+@code{cpu_set_t} object and returns zero.
+
+If @var{pid} does not correspond to a process or thread on the system
+the or the function fails for some other reason, it returns @code{-1}
+and @code{errno} is set to represent the error condition.
+
+@table @code
+@item ESRCH
+No process or thread with the given ID found.
+
+@item EFAULT
+The pointer @var{cpuset} is does not point to a valid object.
+@end table
+
+This function is a GNU extension and is declared in @file{sched.h}.
+@end deftypefun
+
+Note that it is not portably possible to use this information to
+retrieve the information for different POSIX threads. A separate
+interface must be provided for that.
+
+@comment sched.h
+@comment GNU
+@deftypefun int sched_setaffinity (pid_t @var{pid}, const cpu_set_t *@var{cpuset})
+
+This function installs the affinity mask pointed to by @var{cpuset}
+for the process or thread with the ID @var{pid}. If successful the
+function returns zero and the scheduler will in future take the
+affinity information into account.
+
+If the function fails it will return @code{-1} and @code{errno} is set
+to the error code:
+
+@table @code
+@item ESRCH
+No process or thread with the given ID found.
+
+@item EFAULT
+The pointer @var{cpuset} is does not point to a valid object.
+
+@item EINVAL
+The bitset is not valid. This might mean that the affinity set might
+not leave a processor for the process or thread to run on.
+@end table
+
+This function is a GNU extension and is declared in @file{sched.h}.
+@end deftypefun
+
+
@node Memory Resources
@section Querying memory available resources