diff options
Diffstat (limited to 'manual')
-rw-r--r-- | manual/llio.texi | 11 | ||||
-rw-r--r-- | manual/resource.texi | 175 |
2 files changed, 185 insertions, 1 deletions
diff --git a/manual/llio.texi b/manual/llio.texi index e9b5573..4ac6c5f 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -1542,19 +1542,28 @@ empty set. @comment BSD @deftypefn Macro void FD_SET (int @var{filedes}, fd_set *@var{set}) This macro adds @var{filedes} to the file descriptor set @var{set}. + +The @var{filedes} parameter must not have side effects since it is +evaluated more than once. @end deftypefn @comment sys/types.h @comment BSD @deftypefn Macro void FD_CLR (int @var{filedes}, fd_set *@var{set}) This macro removes @var{filedes} from the file descriptor set @var{set}. + +The @var{filedes} parameter must not have side effects since it is +evaluated more than once. @end deftypefn @comment sys/types.h @comment BSD -@deftypefn Macro int FD_ISSET (int @var{filedes}, fd_set *@var{set}) +@deftypefn Macro int FD_ISSET (int @var{filedes}, const fd_set *@var{set}) This macro returns a nonzero value (true) if @var{filedes} is a member of the file descriptor set @var{set}, and zero (false) otherwise. + +The @var{filedes} parameter must not have side effects since it is +evaluated more than once. @end deftypefn Next, here is the description of the @code{select} function itself. 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 |