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

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

[Håkon Bugge]

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().

Signed-off-by: Håkon Bugge <haakon.bugge@oracle.com>
---
 Documentation/memory-barriers.txt | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
index 93d58d9a428b8..d721e9be5a4f5 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -2192,6 +2192,8 @@ interpolate the memory barrier in the right place:
 	wait_event_timeout();
 	wait_on_bit();
 	wait_on_bit_lock();
+	wait_event_cmd();
+	wait_event_exclusive_cmd();
 
 
 Secondly, code that performs a wake up normally follows something like this:
@@ -2296,6 +2298,15 @@ and the waker should do:
 	event_indicated = 1;
 	wake_up(&event_wait_queue);
 
+Note that the wait_event_cmd() and wait_event_exclusive_cmd() are the
+kernel's polymorphic implementation of userspace's
+pthread_cond_wait().
+
+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

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

[Matthew Wilcox]

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?

>  
> +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().

> +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
> 
> 

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

[Haakon Bugge]

> On 26 Jun 2025, at 17:17, Matthew Wilcox <willy@infradead.org> 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
>> 
>>