[Bugme-new] [Bug 9011] New: kernel-locking.tmpl has incorrect and
oversimplified information
bugme-daemon at bugzilla.kernel.org
bugme-daemon at bugzilla.kernel.org
Wed Sep 12 09:55:07 PDT 2007
http://bugzilla.kernel.org/show_bug.cgi?id=9011
Summary: kernel-locking.tmpl has incorrect and oversimplified
information
Product: Other
Version: 2.5
KernelVersion: 2.6.23-rc6-git1
Platform: All
OS/Version: Linux
Tree: Mainline
Status: NEW
Severity: low
Priority: P1
Component: Other
AssignedTo: other_other at kernel-bugs.osdl.org
ReportedBy: mattilinnanvuori at yahoo.com
CC: rdunlap at xenotime.net
Most recent kernel where this bug did not occur: unknown
Problem Description: kernel-locking.tmpl has incorrect path
linux/asm/semaphore.h and oversimplified information about locks. The kernel
lacks documentation about try functions.
Signed-off-by: Matti Linnanvuori <mattilinnanvuori at yahoo.com>
--- linux-2.6.23/Documentation/DocBook/kernel-locking.tmpl 2007-09-12
18:24:20.395574500 +0300
+++ linux-2.6.23-patched/Documentation/DocBook/kernel-locking.tmpl
2007-09-12 19:22:28.425442500 +0300
@@ -225,27 +225,39 @@
There are three main types of kernel locks. The fundamental type
is the spinlock
(<filename class="headerfile">include/asm/spinlock.h</filename>),
- which is a very simple single-holder lock: if you can't get the
- spinlock, you keep trying (spinning) until you can. Spinlocks are
+ which is a very simple single-holder lock. If you can't get the
+ spinlock with <function>spin_lock</function> at any try, you
+ keep retrying (spinning) until you can.
+ <function>spin_trylock</function> does not spin but returns nonzero if it
+ could get the spinlock at the first try or 0 if not. Spinlocks are
very small and fast, and can be used anywhere.
</para>
<para>
The second type is a mutex
(<filename class="headerfile">include/linux/mutex.h</filename>): it
is like a spinlock, but you may block holding a mutex.
- If you can't lock a mutex, your task will suspend itself, and be woken
+ If you can't lock a mutex with <function>mutex_lock</function>
+ at the first try, your task will suspend itself, and be woken
up when the mutex is released. This means the CPU can do something
else while you are waiting. There are many cases when you simply
can't sleep (see <xref linkend="sleeping-things"/>), and so have to
use a spinlock instead.
+ <function>mutex_trylock</function> does not suspend your task
+ but returns nonzero if it could lock the mutex at the first try
+ or 0 if not.
</para>
<para>
The third type is a semaphore
(<filename class="headerfile">include/asm/semaphore.h</filename>): it
can have more than one holder at any time (the number decided at
initialization time), although it is most commonly used as a
- single-holder lock (a mutex). If you can't get a semaphore, your
+ single-holder lock (a mutex). If you can't get a semaphore with
+ <function>down</function> at the first try, your
task will be suspended and later on woken up - just like for mutexes.
+ <function>down_trylock</function> does not suspend your task
+ but returns 0 if it could get the semaphore at the first try or
+ nonzero if not. The return value is the inverse of that of
+ spinlock and mutex.
</para>
<para>
Neither type of lock is recursive: see
@@ -290,7 +302,7 @@
<para>
If you have a data structure which is only ever accessed from
user context, then you can use a simple semaphore
- (<filename>linux/asm/semaphore.h</filename>) to protect it. This
+ (<filename>include/asm/semaphore.h</filename>) to protect it. This
is the most trivial case: you initialize the semaphore to the number
of resources available (usually 1), and call
<function>down_interruptible()</function> to grab the semaphore, and
--
Configure bugmail: http://bugzilla.kernel.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.
More information about the Bugme-new
mailing list