Re: [PATCH v8 9/9] manual: Add documentation for arc4random functions

[Adhemerval Zanella <adhemerval.zanella@linaro.org>]

> On 29 Jun 2022, at 19:05, Noah Goldstein <goldstein.w.n@gmail.com> wrote:
> 
> On Wed, Jun 29, 2022 at 2:53 PM Adhemerval Zanella
> <adhemerval.zanella@linaro.org> wrote:
>> 
>> 
>> 
>>> On 29 Jun 2022, at 18:45, Noah Goldstein <goldstein.w.n@gmail.com> wrote:
>>> 
>>> On Wed, Jun 29, 2022 at 2:36 PM Adhemerval Zanella via Libc-alpha
>>> <libc-alpha@sourceware.org> wrote:
>>>> 
>>>> ---
>>>> manual/math.texi | 45 +++++++++++++++++++++++++++++++++++++++++++++
>>>> 1 file changed, 45 insertions(+)
>>>> 
>>>> diff --git a/manual/math.texi b/manual/math.texi
>>>> index 477a18b6d1..ab96726e57 100644
>>>> --- a/manual/math.texi
>>>> +++ b/manual/math.texi
>>>> @@ -1447,6 +1447,7 @@ systems.
>>>> * ISO Random:: @code{rand} and friends.
>>>> * BSD Random:: @code{random} and friends.
>>>> * SVID Random:: @code{drand48} and friends.
>>>> +* High Quality Random:: @code{arc4random} and friends.
>>>> @end menu
>>>> 
>>>> @node ISO Random
>>>> @@ -1985,6 +1986,50 @@ This function is a GNU extension and should not be used in portable
>>>> programs.
>>>> @end deftypefun
>>>> 
>>>> +@node High Quality Random
>>>> +@subsection High Quality Random Number Functions
>>>> +
>>>> +This section describes the random number functions provided as a GNU
>>>> +extension, based on OpenBSD interfaces.
>>>> +
>>>> +@Theglibc{} uses kernel entropy obtained either through @code{getrandom}
>>>> +or by reading @file{/dev/urandom} to seed and periodically re-seed the
>>>> +internal state. A per-thread data pool is used, which allows fast output
>>>> +generation.
>>>> +
>>> 
>>> Are we committing to per-thread data pools? I thought there were ideas to
>>> use rseq.
>> 
>> For this version yes, since it works on all supported kernels (even for the
>> ones without getentropy support) and on all architectures.  I do not know how
>> feasible it would be to implement per-cpu caches along with rseq and it would
>> require a fallback for older kernel (most likely a per-thread cache as this
>> version), although it might be future improvement.
> 
> I guess do we want to explicitly say per-thread buffer if we may want
> to experiment
> with something else?
> 
> Just seems like the kind of thing that might make it impossible to re-implement
> another way.
> 
> What about something like:
> 
> "The data-pool is implemented to minimize cross-core contention
> allowing fast output generation”?

I take the idea is to avoid adding too much implementation detail to manual,
although I take that documentation and arc4random specification does not
define performance or complexity details (as for some STL containers for
instance). If we even change the arc4random implementation I would expect
to update this documentation description.

But iIt does make sense to define expectations, so I will update with your
suggestion (and Yann remarks).