Re: [gomp] GOMP_CPU_AFFINITY support

[Brooks Moses <brooks dot moses at codesourcery dot com>]

(This may be a duplicate; my mail server glitched and I can't tell if 
this got sent to everyone or not.  Sigh.)

Daniel Franke wrote:
> Ok for trunk?

Some minor typo fixes and comments:

> @@ -895,14 +895,24 @@
>  @cindex Environment Variable
>  @table @asis
>  @item @emph{Description}:
> -A patch for this extension has been submitted, but was not yet applied at the
> -time of writing.
> +Binds threads to specific CPUs. The variable should contain space or

"contain a space"

> +comma separated list of CPUs, e. g. either a zero based CPU number, or a
> +range of CPUs (M-N) or a range with some stride (M-N:S). For example,

Those don't seem like examples of "space or comma separated lists of 
CPUs"; I think this could be written a little more clearly.  Also, I 
would put "The CPU numbers are zero-based" as a separate sentence, 
rather than tucking it into a clause of this list.

Also, pedantically, that should be "space- or comma-separated"; compound 
adjectives get hyphens.  And I think (but am not sure) that house style 
for "e.g." is to omit the space, and always follow it with a comma.

> +@code{GOMP_CPU_AFFINITY="0 3 1-2 4-15:2"} will bind the initial thread
> +to CPU 0, the second to CPU 3, the third to CPU 1, the fourth to 
> +CPU 2, the fifth to CPU 4, the sixth to CPU 6, the seventh to CPU 8, ... 
> +tenth to CPU 14 and then starts assigning back from the beginning of the 

"then start assigning".

The "..." looks a bit too sketchy for my tastes; maybe "the sixth 
through tenth to CPUs 6, 8, 10, 12, and 14 respectively, and then..."? 
(At least, make that "the tenth to".)

> +list. @code{GOMP_CPU_AFFINITY=0} binds all threads to CPU 0.

Giving examples like this is definitely a good thing; well done!  (I 
would put the simple example first, though.)

> -@item @emph{Reference}: 
> -@uref{http://gcc.gnu.org/ml/gcc-patches/2006-05/msg00982.html, 
> -GCC Patches Mailinglist}
> -@uref{http://gcc.gnu.org/ml/gcc-patches/2006-05/msg01133.html,
> -GCC Patches Mailinglist}
> +There is no GNU OpenMP library routine to determine whether CPU affinity 
> +is in effect. As a workaround, language specific library functions, e. g. 

See earlier comment about "e.g.".  I'd also word that as "a CPU affinity 
specification" or "a CPU affinitiy environment variable", rather than 
just "CPU affinity".

Also: "language-specific".  (Compound adjective, again.)

> +@code{getenv} in C or @code{GET_ENVIRONMENT_VARIABLE} in Fortran, may 
> +be used to query the setting of the environment variable. A defined CPU 

"the @code{GOMP_CPU_AFFINITY} environment variable", I'd say, just to be 
completely clear.  Or maybe just "this environment variable".

> +affinity on startup can not be changed or disabled during the runtime of 
> +the application.

"cannot".

I would also suggest "while the application is running", but that's just 
opinion.  :)

> +If this environment variable is omitted, the host system while handle the 
> +assignment of threads to CPUs. 
>  @end table

"system will handle".

I do want to point out that I don't think the quantity of virtual red 
ink I just applied to this is any reflection on the quality -- it looks 
well-written and clear to me!  :)

- Brooks