[RFC PATCH 1/1] local_lock: Minor improvements of local_trylock*() documentation

[RFC PATCH 1/1] local_lock: Minor improvements of local_trylock*() documentation

[Leonardo Bras]

Fix local_trylock_init() documentation, as it was mentioning the non-try
helper instead, and use the opportunity to make clear the try_lock*() needs
to receive a try-enabled variable as parameter.

Signed-off-by: Leonardo Bras <leobras@redhat.com>
---
 include/linux/local_lock.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/include/linux/local_lock.h b/include/linux/local_lock.h
index 16a2ee4f8310b..e052e33432cb2 100644
--- a/include/linux/local_lock.h
+++ b/include/linux/local_lock.h
@@ -45,38 +45,38 @@
 /**
  * local_unlock_irqrestore - Release a per CPU local lock and restore
  *			      interrupt flags
  * @lock:	The lock variable
  * @flags:      Interrupt flags to restore
  */
 #define local_unlock_irqrestore(lock, flags)			\
 	__local_unlock_irqrestore(lock, flags)
 
 /**
- * local_lock_init - Runtime initialize a lock instance
+ * local_trylock_init - Runtime initialize a try-enabled lock instance
  */
 #define local_trylock_init(lock)	__local_trylock_init(lock)
 
 /**
  * local_trylock - Try to acquire a per CPU local lock
- * @lock:	The lock variable
+ * @lock:	The try-enabled lock variable
  *
  * The function can be used in any context such as NMI or HARDIRQ. Due to
  * locking constrains it will _always_ fail to acquire the lock in NMI or
  * HARDIRQ context on PREEMPT_RT.
  */
 #define local_trylock(lock)		__local_trylock(lock)
 
 /**
  * local_trylock_irqsave - Try to acquire a per CPU local lock, save and disable
  *			   interrupts if acquired
- * @lock:	The lock variable
+ * @lock:	The try-enabled lock variable
  * @flags:	Storage for interrupt flags
  *
  * The function can be used in any context such as NMI or HARDIRQ. Due to
  * locking constrains it will _always_ fail to acquire the lock in NMI or
  * HARDIRQ context on PREEMPT_RT.
  */
 #define local_trylock_irqsave(lock, flags)			\
 	__local_trylock_irqsave(lock, flags)
 
 DEFINE_GUARD(local_lock, local_lock_t __percpu*,
-- 
2.49.0

Re: [RFC PATCH 1/1] local_lock: Minor improvements of local_trylock*() documentation

[Sebastian Andrzej Siewior]

On 2025-04-30 04:36:10 [-0300], Leonardo Bras wrote:
> Fix local_trylock_init() documentation, as it was mentioning the non-try
> helper instead, and use the opportunity to make clear the try_lock*() needs
> to receive a try-enabled variable as parameter.

Maybe replaced "try-enabled lock" with "local_trylock_t". "Try enabled
lock" as mentioned in the documentation or "try-enabled variable" as here
in the description does not really fit.

> Signed-off-by: Leonardo Bras <leobras@redhat.com>

Sebastian

Re: [RFC PATCH 1/1] local_lock: Minor improvements of local_trylock*() documentation

[Vlastimil Babka]

On 4/30/25 16:59, Sebastian Andrzej Siewior wrote:
> On 2025-04-30 04:36:10 [-0300], Leonardo Bras wrote:
>> Fix local_trylock_init() documentation, as it was mentioning the non-try
>> helper instead, and use the opportunity to make clear the try_lock*() needs
>> to receive a try-enabled variable as parameter.
> 
> Maybe replaced "try-enabled lock" with "local_trylock_t". "Try enabled
> lock" as mentioned in the documentation or "try-enabled variable" as here
> in the description does not really fit.

I agree, it's more clear that way.

Thanks,
Vlastimil

>> Signed-off-by: Leonardo Bras <leobras@redhat.com>
> 
> Sebastian

Re: [RFC PATCH 1/1] local_lock: Minor improvements of local_trylock*() documentation

[Leonardo Bras]

On Mon, May 05, 2025 at 10:01:32AM +0200, Vlastimil Babka wrote:
> On 4/30/25 16:59, Sebastian Andrzej Siewior wrote:
> > On 2025-04-30 04:36:10 [-0300], Leonardo Bras wrote:
> >> Fix local_trylock_init() documentation, as it was mentioning the non-try
> >> helper instead, and use the opportunity to make clear the try_lock*() needs
> >> to receive a try-enabled variable as parameter.
> > 
> > Maybe replaced "try-enabled lock" with "local_trylock_t". "Try enabled
> > lock" as mentioned in the documentation or "try-enabled variable" as here
> > in the description does not really fit.
> 
> I agree, it's more clear that way.
> 
> Thanks,
> Vlastimil
> 
> >> Signed-off-by: Leonardo Bras <leobras@redhat.com>
> > 
> > Sebastian
> 


Hi Sebastian, Vlastimil,

Thanks for the feedback!
I implemented the suggested changes and just sent a v1 for this patch, 
which can be seen in:
https://lore.kernel.org/all/20250505170244.253170-1-leobras@redhat.com/T/#u

Thanks!
Leo