Re: For review: pthread_attr_setaffinity_np.3

[Loic Domaigne <tech-Z4JMKDdsf89Wk0Htik3J/w@public.gmane.org>]

Hi Michael,

see my comments below (refer also to my comments for 
pthread_setaffinity_np.3).

Cheers,
Loïc.
--

> .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
> .\"     <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> .\"
> .\" Permission is granted to make and distribute verbatim copies of this
> .\" manual provided the copyright notice and this permission notice are
> .\" preserved on all copies.
> .\"
> .\" Permission is granted to copy and distribute modified versions of this
> .\" manual under the conditions for verbatim copying, provided that the
> .\" entire resulting derived work is distributed under the terms of a
> .\" permission notice identical to this one.
> .\"
> .\" Since the Linux kernel and libraries are constantly changing, this
> .\" manual page may be incorrect or out-of-date.  The author(s) assume no
> .\" responsibility for errors or omissions, or for damages resulting from
> .\" the use of the information contained herein.  The author(s) may not
> .\" have taken the same level of care in the production of this manual,
> .\" which is licensed free of charge, as they might when working
> .\" professionally.
> .\"
> .\" Formatted or processed versions of this manual, if unaccompanied by
> .\" the source, must acknowledge the copyright and authors of this work.
> .\"
> .TH PTHREAD_ATTR_SETAFFINITY_NP 3 2008-11-05 "Linux" "Linux Programmer's Manual"

Title looks weird on a 80x24 terminal.


> .SH NAME
> pthread_attr_setaffinity_np, pthread_attr_getaffinity_np \- set/get
> CPU affinity of a thread

You surely mean: "CPU affinity attribute of a thread"


> .SH SYNOPSIS
> .nf
> .B #define _GNU_SOURCE
> .B #include <pthread.h>
> 
> .BI "int pthread_attr_setaffinity_np(pthread_attr_t " attr ,
> .BI "                   size_t " cpusetsize ", const cpu_set_t *" cpuset );
> .BI "int pthread_attr_getaffinity_np(pthread_attr_t " attr ,
> .BI "                   size_t " cpusetsize ", cpu_set_t *" cpuset );
> .sp
> Compile and link with \fI\-pthread\fP.
> .SH DESCRIPTION
> The
> .BR pthread_attr_setaffinity_np ()
> sets the CPU affinity mask attribute of the
> thread attributes object referred to by
> .I attr
> to the value specified in
> .IR cpuset .
> This attribute determines the CPU affinity mask
> of a thread created using the thread attributes object
> .IR attr .
> 
> The
> .BR pthread_attr_getaffinity_np ()
> returns the CPU affinity mask attribute of the thread attributes object
> referred to by
> .IR attr
> in the buffer pointed to by
> .IR cpuset .
> 
> The argument
> .I cpusetsize
> is the length (in bytes) of the buffer pointed to by
> .IR cpuset .
> Normally this argument would be specified as
> .IR sizeof(cpu_set_t) .
> The constant
> .B CPU_SETSIZE
> specifies a value one greater than the
> maximum CPU number that can be stored in a CPU set.
> 
> For more details on CPU affinity masks,
> as well as a description of a set of macros
> that can be used to manipulate and inspect CPU sets, see
> .BR sched_setaffinity (2)
> for details.
> .SH RETURN VALUE
> On success, these functions return 0;
> on error, they return a non-zero error number.
> .SH ERRORS
> .TP
> .B EINVAL
> .I attr
> or
> .I cpuset
> is invalid.

I beg your pardon, but I couldn't find where those checks are performed 
in the relevant glibc files... Perhaps I am not looking at the right place?

> .TP
> .BR EINVAL
> .RB ( pthread_attr_setaffinity_np ())
> .I cpuset
> specified a CPU that was outside the range
> permitted by the kernel data type
> .\" cpumask_t
> used to represent CPU sets.
> .\" The raw sched_getaffinity() system call returns the size (in bytes)
> .\" of the cpumask_t type.
> This range is determined by the kernel configuration option
> .BR CONFIG_NR_CPUS .

<check>
Hmmm. What does happen if CPU set contains no CPU physically on the 
system when the thread is created? I guess pthread_create() fails?
</check>

> .TP
> .B EINVAL
> .RB ( pthread_getaffinity_np ())

This should be: pthread_attr_getaffinity_np().


> A CPU in the affinity mask of the thread attributes object referred to by
> .I attr
> lies outside the range specified by
> .IR cpusetsize .

For the application programmer, this means that the structure I passed 
for storing the CPU set wasn't big enough to store thread's CPU set 
without loosing "affinity information".


> .TP
> .B ENOMEM
> .RB ( pthread_attr_setaffinity_np ())
> Could not allocate memory.

Correct. However, the glibc looks somewhat suspicious to me: I had 
expected the memory allocated by iattr->cpuset to be bounded (by the 
size of the underlying kernel structure).

Or perhaps I am just missing my coffeine :o

> .SH VERSIONS
> These functions are provided by glibc since version 2.3.4.
> .SH CONFORMING TO
> These functions are non-standard GNU extensions;
> hence the suffix "_np" (non-portable) in the names.
> .SH NOTES
> In glibc 2.3.3 only,
> versions of these functions were provided that did not have a
> .I cpusetsize
> argument.
> Instead the CPU set size given to the underlying system calls was always
> .IR sizeof(cpu_set_t) .
> .SH SEE ALSO
> .BR sched_setaffinity (2),
> .BR sched_setscheduler (2),

Why the reference to sched_setscheduler()?

> .BR pthread_attr_init (3),
> .BR pthread_setaffinity_np (3),
> .BR cpuset (7),
> .BR pthreads (7)
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html