locking/mutex: Improve documentation

On Wed, Mar 14, 2018 at 01:56:31PM -0700, Andrew Morton wrote:

> My memory is weak and our documentation is awful.  What does
> mutex_lock_killable() actually do and how does it differ from
> mutex_lock_interruptible()?

Add kernel-doc for mutex_lock_killable() and mutex_lock_io().  Reword the
kernel-doc for mutex_lock_interruptible().

Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Kirill Tkhai <ktkhai@virtuozzo.com>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: cl@linux.com
Cc: tj@kernel.org
Link: http://lkml.kernel.org/r/20180315115812.GA9949@bombadil.infradead.org
Signed-off-by: Ingo Molnar <mingo@kernel.org>
This commit is contained in:
Matthew Wilcox 2018-03-15 04:58:12 -07:00 committed by Ingo Molnar
parent 1b5f3ba415
commit 45dbac0e28
1 changed files with 30 additions and 7 deletions

View File

@ -1082,15 +1082,16 @@ static noinline int __sched
__mutex_lock_interruptible_slowpath(struct mutex *lock);
/**
* mutex_lock_interruptible - acquire the mutex, interruptible
* @lock: the mutex to be acquired
* mutex_lock_interruptible() - Acquire the mutex, interruptible by signals.
* @lock: The mutex to be acquired.
*
* Lock the mutex like mutex_lock(), and return 0 if the mutex has
* been acquired or sleep until the mutex becomes available. If a
* signal arrives while waiting for the lock then this function
* returns -EINTR.
* Lock the mutex like mutex_lock(). If a signal is delivered while the
* process is sleeping, this function will return without acquiring the
* mutex.
*
* This function is similar to (but not equivalent to) down_interruptible().
* Context: Process context.
* Return: 0 if the lock was successfully acquired or %-EINTR if a
* signal arrived.
*/
int __sched mutex_lock_interruptible(struct mutex *lock)
{
@ -1104,6 +1105,18 @@ int __sched mutex_lock_interruptible(struct mutex *lock)
EXPORT_SYMBOL(mutex_lock_interruptible);
/**
* mutex_lock_killable() - Acquire the mutex, interruptible by fatal signals.
* @lock: The mutex to be acquired.
*
* Lock the mutex like mutex_lock(). If a signal which will be fatal to
* the current process is delivered while the process is sleeping, this
* function will return without acquiring the mutex.
*
* Context: Process context.
* Return: 0 if the lock was successfully acquired or %-EINTR if a
* fatal signal arrived.
*/
int __sched mutex_lock_killable(struct mutex *lock)
{
might_sleep();
@ -1115,6 +1128,16 @@ int __sched mutex_lock_killable(struct mutex *lock)
}
EXPORT_SYMBOL(mutex_lock_killable);
/**
* mutex_lock_io() - Acquire the mutex and mark the process as waiting for I/O
* @lock: The mutex to be acquired.
*
* Lock the mutex like mutex_lock(). While the task is waiting for this
* mutex, it will be accounted as being in the IO wait state by the
* scheduler.
*
* Context: Process context.
*/
void __sched mutex_lock_io(struct mutex *lock)
{
int token;