Re: [PATCH 1/1] docs/memory-barriers.txt: Add wait_event_cmd() and wait_event_exclusive_cmd()

> On 26 Jun 2025, at 17:17, Matthew Wilcox <[email protected]> wrote:
> 
> On Thu, Jun 26, 2025 at 04:37:05PM +0200, Håkon Bugge wrote:
>> Add said functions to the documentation and relate them to userspace's
>> pthread_cond_wait(). The latter because when searching for
>> functionality comparable to pthread_cond_wait(), it is very hard to
>> find wait_event_cmd().
> 
> Would it not go better in the kernel-doc for wait_event_cmd() in
> include/linux/wait.h?

What about both? The list with wait_foo_bars() in Documentation/memory-barriers.txt misses wait_event_cmd() and wait_event_exclusive_cmd().

But my prosaic explanation could very well go into include/linux/wait.h

>> +Note that the wait_event_cmd() and wait_event_exclusive_cmd() are the
>> +kernel's polymorphic implementation of userspace's
>> +pthread_cond_wait().
> 
> Pet peeve: "Note that" adds nothing to this sentence.  You can just
> write:
> 
> The wait_event_cmd() and wait_event_exclusive_cmd() functions are the
> kernel's polymorphic implementation of userspace's pthread_cond_wait().

Me blushing! +1

Thxs, Håkon

> 
>> +Using wait_event_cmd() or wait_event_exclusive_cmd(), cmd1 is
>> +typically a lock-release call and cmd2 a lock-acquire call. The
>> +locking primitive can be chosen, contrary to pthread_cond_wait(),
>> +where the locking type is cast in stone and is a pthread_mutex_t.
>> +
>> 
>> MISCELLANEOUS FUNCTIONS
>> -----------------------
>> -- 
>> 2.43.5
>> 
>>