Re: [PATCH] prctl: Add documentation for PR_FUTEX_HASH

[Sebastian Andrzej Siewior <bigeasy@linutronix.de>]

On 2025-05-17 15:41:26 [+0200], Alejandro Colomar wrote:
> Hi Sebastian,
Hi Alejandro,

> > diff --git a/man/man2const/PR_FUTEX_HASH.2const b/man/man2const/PR_FUTEX_HASH.2const
> > new file mode 100644
> > index 0000000000000..c6a6396729770
> > --- /dev/null
> > +++ b/man/man2const/PR_FUTEX_HASH.2const
> > @@ -0,0 +1,112 @@
…
> > +Configure the attributes for the underlying hash used by the
> > +.BR futex (2)
> > +family of operations. The Linux kernel uses a hash to distributes the
> 
> Please use semantic newlines.  See man-pages(7):
> 
> $ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
>    Use semantic newlines
>        In the source of a manual page, new sentences should be  started
>        on  new  lines,  long  sentences  should  be split into lines at
>        clause breaks (commas, semicolons, colons, and so on), and  long
>        clauses  should be split at phrase boundaries.  This convention,
>        sometimes known as "semantic newlines", makes it easier  to  see
>        the effect of patches, which often operate at the level of indi‐
>        vidual sentences, clauses, or phrases.
> 

Understood.

> Also, thanks to semantic newlines, we don't need to think about the
> amount of spaces after a '.'.  However, for *roff, you need to use two
> spaces in the source code after a period that ends a sentence; else it
> is interpreted as not ending a sentence, and the resulting document is
> clearly bad.  I recommend reading this:
> 
> $ cat CONTRIBUTING.d/patches/description | sed -n '/inter-sentence/,/^$/p'
> 	The correct inter-sentence space amount is two.  See some
> 	history about this:
> 	<https://web.archive.org/web/20171217060354/http://www.heracliteanriver.com/?p=324>

Okay. In the source code. Otherwise new line.

…
> > +problematic on a PREEMPT_RT system since random tasks can share in-kernel locks
> 
> References to PREEMPT_RT in existing pages use CONFIG_PREEMPT_RT.
> Should we do the same?

After looking through it, I switched to "real-time".

> 	$ grep -rn PREEMPT_RT man/
> 	man/man7/sched.7:969:.B CONFIG_PREEMPT_RT
> 	man/man2/futex.2:1326:.\" PREEMPT_RT-enabled Linux systems.

but looking here, it could be updated that the major piece of the
patches has been merged and the mentioned config option is available.

> > +and it is not deterministic which tasks will be involved.
> > +.P
> > +Linux v6.16 implements a process wide private hash which is used by all
> > +.BR futex (2)
> > +operations which specify the
> > +.B FUTEX_PRIVATE_FLAG
> > +as part of the operation.
> > +Without any configuration the kernel will allocate 16 hash slots once the first
> > +thread has been created. If the process continues to create threads, the kernel
> > +will try to resize the private hash based on the number of threads and
> > +available CPUs in the system. The kernel will only increase the size and will
> > +make sure it does not exceed the size of the global hash.
> > +.P
> > +The user can configure the size of the private hash which will also disable the
> > +automatic resize provided by the kernel.
> > +.P
> > +The following values for
> > +.I op
> > +can be specified:
> > +.TP
> > +.BI "int prctl(PR_FUTEX_HASH, PR_FUTEX_HASH_SET_SLOTS, " hash_size ", " hash_flags ");
> 
> What's the type of hash_size and hash_flags?

it is unsigned long as per prctl() prototype. I added it here.

Sebastian