[patch v1] manual: add remaining CPU_* macros

[Florian Weimer]

* DJ Delorie:

> Adds remaining CPU_* macros, including the CPU_*_S macros
> for dynamic-sized cpu sets.
>
> diff --git a/manual/resource.texi b/manual/resource.texi
> index acdb1f3986..739c019c8c 100644
> --- a/manual/resource.texi
> +++ b/manual/resource.texi
> @@ -1424,6 +1424,39 @@ evaluated more than once.
>  This macro is a GNU extension and is defined in @file{sched.h}.
>  @end deftypefn
>  
> +@deftypefn Macro {cpu_set_t *} CPU_AND (cpu_set_t *@var{dest}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2})
> +@standards{GNU, sched.h}
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c CPU_AND ok
> +@c  __CPU_OP_S ok
> +This macro populates @var{dest} with only those CPUs included in both
> +@var{src1} and @var{src2}.  Its value is @var{dest}.
> +
> +This macro is a GNU extension and is defined in @file{sched.h}.
> +@end deftypefn

As a general comment, I think the fixed-size macros should be
deprecated.  Machines with more than 1024 CPUs are making a comeback.
The fixed-size cpu_set_t type does not work for them.  In particular,
sched_getcpu might fail.

Here's a recent example:

  [PATCH v2] nproc: Use affinity mask even on systems with more than 1024 CPUs
  <https://lists.gnu.org/archive/html/bug-gnulib/2024-11/msg00084.html>

  [PATCH] build: update gnulib to latest
  <https://lists.gnu.org/archive/html/coreutils/2024-11/msg00013.html>

Perhaps even quote the code in the first patch as an example in the
manual?

> +For applications that require CPU sets larger than the built-in size,
> +a set of macros that support dynamically-sized sets are defined.
> +
> +@deftypefn Macro size_t CPU_ALLOC_SIZE (size_t @var{count})
> +@standards{GNU, sched.h}
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c CPU_ALLOC_SIZE ok
> +@c  __CPU_ALLOC_SIZE ok
> +Given a count of CPUs to hold, returns the size of the set to
> +allocate.  This return value is appropriate to be used in the *_S macros.
> +
> +This macro is a GNU extension and is defined in @file{sched.h}.
> +@end deftypefn
> +
> +@deftypefn Macro {cpu_set_t *} CPU_ALLOC (size_t @var{count})
> +@standards{GNU, sched.h}
> +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
> +@c CPU_ALLOC
> +@c  __CPU_ALLOC
> +@c   __sched_cpualloc
> +@c    malloc
> +Given the count of CPUs to hold, returns a set large enough to hold
> +them; that is, the resulting set will be valid for CPUs numbered 0
> +through @var{count}-1, inclusive.  This set is allocated with
> +@code{malloc} and must be freed via @code{CPU_FREE}.
> +
> +This macro is a GNU extension and is defined in @file{sched.h}.
> +@end deftypefn

Maybe mention explicitly that the argument is *not* the result of
CPU_ALLOC_SIZE?

If the allocation happens via malloc, why require that CPU_FREE must be
used?  Maybe drop the malloc reference in the visible text?

> +@deftypefn Macro void CPU_ZERO_S (size_t @var{size}, cpu_set_t *@var{set})
> +@end deftypefn
> +@deftypefn Macro void CPU_SET_S (int @var{cpu}, size_t @var{size}, cpu_set_t *@var{set})
> +@end deftypefn
> +@deftypefn Macro void CPU_CLR_S (int @var{cpu}, cpu_set_t *@var{set})
> +@end deftypefn
> +@deftypefn Macro {cpu_set_t *} CPU_AND_S (size_t @var{size}, cpu_set_t *@var{dest}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2})
> +@end deftypefn
> +@deftypefn Macro {cpu_set_t *} CPU_OR_S (size_t @var{size}, cpu_set_t *@var{dest}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2})
> +@end deftypefn
> +@deftypefn Macro {cpu_set_t *} CPU_XOR_S (size_t @var{size}, cpu_set_t *@var{dest}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2})
> +@end deftypefn
> +@deftypefn Macro int CPU_ISSET_S (int @var{cpu}, size_t @var{size}, const cpu_set_t *@var{set})
> +@end deftypefn
> +@deftypefn Macro int CPU_COUNT_S (size_t @var{size}, const cpu_set_t *@var{set})
> +@end deftypefn
> +@deftypefn Macro int CPU_EQUAL_S (size_t @var{size}, cpu_set_t *@var{src1}, cpu_set_t *@var{src2})
> +@end deftypefn
> +
> +Each of these macros performs the same action as its non-@code{_S} variant,
> +but takes a @var{size} argument to specify the set size.  This
> +@var{size} argument is as returned by the @code{CPU_ALLOC_SIZE} macro,
> +defined above.

I think it would make sense to mention the *_S macros first and

Thanks,
Florian