[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