Skip to contentSkip to conversation

local_lock: Minor improvements of local_trylock*() documentation

RFC PATCH In review Leonardo Bras 3 participants 4 messages Apr 30, 2025 – May 5, 2025 Locking primitives

lore
Share & tools
lore
#0 lore raw

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

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.

---
 include/linux/local_lock.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
include/linux/local_lock.h +3 -3
index 16a2ee4f8310b..e052e33432cb2 100644
@@ -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*,
Signature · 1 line
2.49.0
#1 lore raw
Quoted 3 lines · 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.

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.

Quoted 1 line

Sebastian

#2 lore raw
Quoted 8 lines · Sebastian Andrzej Siewior
Quoted 3 lines · 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.

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

Quoted 3 lines
Quoted 1 line

Sebastian

#3 lore raw
Quoted 6 lines · Vlastimil Babka
Quoted 5 lines · Sebastian Andrzej Siewior
Quoted 3 lines · 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.

Quoted 13 lines
Quoted 3 lines

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

Quoted 3 lines
Quoted 1 line

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/[email protected]/T/#u

Thanks!
Leo