Subject: doc: add a chapter about trylock functions [Bug 9011] Date: Tue, 13 May 2008 18:31:47 +0300 From: Matti Linnanvuori Add a chapter about trylock functions. http://bugzilla.kernel.org/show_bug.cgi?id=9011 Signed-off-by: Matti Linnanvuori Signed-off-by: Rusty Russell --- Documentation/DocBook/kernel-locking.tmpl | 33 ++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff -r 12b5ad48554a Documentation/DocBook/kernel-locking.tmpl --- a/Documentation/DocBook/kernel-locking.tmpl Thu May 15 10:25:14 2008 +1000 +++ b/Documentation/DocBook/kernel-locking.tmpl Thu May 15 10:31:28 2008 +1000 @@ -701,6 +701,39 @@ + + + + The trylock Functions + + There are functions that try to acquire a lock only once and immediately + return a value telling about success or failure to acquire the lock. + They can be used if you need no access to the data protected with the lock + when some other thread is holding the lock. You should acquire the lock + later if you then need access to the data protected with the lock. + + + + spin_trylock() does not spin but returns non-zero if + it acquires the spinlock on the first try or 0 if not. This function can + be used in all contexts like spin_lock: you must have + disabled the contexts that might interrupt you and acquire the spin lock. + + + + mutex_trylock() does not suspend your task + but returns non-zero if it could lock the mutex on the first try + or 0 if not. This function cannot be safely used in hardware or software + interrupt contexts despite not sleeping. + + + + down_trylock() does not suspend your task + but returns 0 if it could get the semaphore on the first try or + non-zero if not. The return value is the inverse of that of + spin_trylock() and mutex_trylock() + . down_trylock can be used in all contexts. +