For review: pthread_attr_setaffinity_np.3

For review: pthread_attr_setaffinity_np.3

[Michael Kerrisk]

Hi all,

And yet another new pthreads man page looking for reviewers.

Cheers,

Michael

.\" 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"
.SH NAME
pthread_attr_setaffinity_np, pthread_attr_getaffinity_np \- set/get
CPU affinity 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.
.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 .
.TP
.B EINVAL
.RB ( pthread_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 .
.TP
.B ENOMEM
.RB ( pthread_attr_setaffinity_np ())
Could not allocate memory.
.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),
.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

Re: For review: pthread_attr_setaffinity_np.3

[Bert Wesarg]

On Wed, Nov 12, 2008 at 22:54, Loic Domaigne <tech@domaigne.com> wrote:
> 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@gmail.com>
>> .\"
>> .\" 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).
But this kernel structure is not bounded, it depends on the compile
time constant CONFIG_NR_CPUS (or in the future on the kernel runtime
variable nr_cpus_id), therefore glibc can't know this a-priori. (but I
haven't looked into the code)

>
> 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)
>>
>
>

Re: For review: pthread_attr_setaffinity_np.3

[Loic Domaigne]

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

Re: For review: pthread_attr_setaffinity_np.3

[Michael Kerrisk]

Hi Loïc,

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

Thanks very much!  Follow-ups below.

[...]

>> .TH PTHREAD_ATTR_SETAFFINITY_NP 3 2008-11-05 "Linux" "Linux Programmer's
>> Manual"
>
> Title looks weird on a 80x24 terminal.

Yes.  But, hard to help -- I couldn't think of a reasonable, more
abbreviated name for the page title.

>> .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"

Acchh.  You caught cut-and-paste-Pete at work.  Fixed:

==
pthread_attr_setaffinity_np, pthread_attr_getaffinity_np \- set/get
CPU affinity attribute in thread attributes object
==

[...]

>> .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?

Hmmm.  I'm not sure how I came to add that text.  I've removed it now.

>> .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 .

(While we're here: I changed the text of this EINVAL error to be the
same as the revised EINVAL error text in ptherad_setaffinity_np(3).)

> <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>

I would expect pthread_create() to fail with EINVAL, and testing
confirms this.  (There is an EINVAL error diagnostic in
pthread_create(3): "Invalid settings in attr".)

>> .TP
>> .B EINVAL
>> .RB ( pthread_getaffinity_np ())
>
> This should be: pthread_attr_getaffinity_np().

Fixed now.

>> 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".

I simply added the words:

(i.e., cpuset/cpusetsize is too small)

>> .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

Not sure if you are suggesting that I need to change anything here?

[...]

>> .SH SEE ALSO
>> .BR sched_setaffinity (2),
>> .BR sched_setscheduler (2),
>
> Why the reference to sched_setscheduler()?

I had thought to include it since it gives some background generally
about CPU scheduling.  Maybe it's not really necessary: I've removed
it now.

Thanks for these comments Loic.

The revised page is below.

Cheers,

Michael

.\" 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-14 "Linux" "Linux Programmer's Manual"
.SH NAME
pthread_attr_setaffinity_np, pthread_attr_getaffinity_np \- set/get
CPU affinity attribute in thread attributes object
.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 .
Typically, this argument would be specified as
.IR sizeof(cpu_set_t) .

For more details on CPU affinity masks, see
.BR sched_setaffinity (2).
For a description of a set of macros
that can be used to manipulate and inspect CPU sets, see
.BR CPU_SET (3).
.SH RETURN VALUE
On success, these functions return 0;
on error, they return a non-zero error number.
.SH ERRORS
.TP
.BR EINVAL
.RB ( pthread_attr_setaffinity_np ())
.I cpuset
specified a CPU that was outside the set supported by the kernel.
(The kernel configuration option
.BR CONFIG_NR_CPUS
defines the range of the set supported 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.
.TP
.B EINVAL
.RB ( 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
(i.e.,
.IR cpuset / cpusetsize
is too small).
.TP
.B ENOMEM
.RB ( pthread_attr_setaffinity_np ())
Could not allocate memory.
.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 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

Re: For review: pthread_attr_setaffinity_np.3

[Loic Domaigne]

Hi Bert!


>>> .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).
> But this kernel structure is not bounded, it depends on the compile
> time constant CONFIG_NR_CPUS (or in the future on the kernel runtime
> variable nr_cpus_id), therefore glibc can't know this a-priori. (but I
> haven't looked into the code)

AFAICS, the kernel structure size is determined at runtime by glibc on 
the first call of pthread_setaffinity_np() or 
pthread_attr_setaffinity_np(). Please refer to the function 
__determine_cpumask_size() in 
nptl/sysdeps/unix/sysv/linux/pthread_setaffinity.c

Once you know this structure size, there is no reason to allocate a 
bigger room for the attribute cpuset iattr->cpuset. As of glibc-2.7, the 
memory size allocated is based on the cupsetsize argument passed to 
pthread_attr_setaffinity_np() without respect to the underlying kernel 
structure.

Of course the Linux & Glibc folks might have some future plans that may 
not be easily inferred from the actual source.

Loïc.
--
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

Re: For review: pthread_attr_setaffinity_np.3

[Loic Domaigne]

Hi Michael,


>>> .TH PTHREAD_ATTR_SETAFFINITY_NP 3 2008-11-05 "Linux" "Linux Programmer's
>>> Manual"
>> Title looks weird on a 80x24 terminal.
> 
> Yes.  But, hard to help -- I couldn't think of a reasonable, more
> abbreviated name for the page title.

Sure. I just reviewed using the '-pedantic' flag :-D


>>> .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 .
> 
> (While we're here: I changed the text of this EINVAL error to be the
> same as the revised EINVAL error text in ptherad_setaffinity_np(3).)
> 
>> <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>
> 
> I would expect pthread_create() to fail with EINVAL, and testing
> confirms this.  (There is an EINVAL error diagnostic in
> pthread_create(3): "Invalid settings in attr".)

Fine. I expected something like that, but I didn't got the opportunity 
to check it. Thanks.


>>> .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
> 
> Not sure if you are suggesting that I need to change anything here?

I suggest to change the glibc code, not your description.


> .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
> .\"     <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>

[snip]

The revised version looks good to me.

Cheers,
Loïc.
--
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