LOCK(9)                      NetBSD Kernel Manual                      LOCK(9)

NAME
     lock, simple_lock_init, simple_lock, simple_lock_try, simple_unlock,
     simple_lock_freecheck, simple_lock_dump, lockinit, lockmgr, lockstatus,
     lockmgr_printinfo, spinlockinit, spinlockmgr - kernel lock functions

SYNOPSIS
     #include <sys/lock.h>

     void
     simple_lock_init(struct simplelock *slock);

     void
     simple_lock(struct simplelock *slock);

     int
     simple_lock_try(struct simplelock *slock);

     void
     simple_unlock(struct simplelock *slock);

     void
     simple_lock_freecheck(void *start, void *end);

     void
     simple_lock_dump(void);

     void
     lockinit(struct lock *lock, int prio, const char *wmesg, int timo,
             int flags);

     int
     lockmgr(struct lock *lock, u_int flags, struct simplelock *slock);

     int
     lockstatus(struct lock *lock);

     void
     lockmgr_printinfo(struct lock *lock);

     void
     spinlockinit(struct lock *lock, const char *wmesg, int flags);

     int
     spinlockmgr(struct lock *lock, u_int flags, struct simplelock *slock);

DESCRIPTION
     The lock functions provide synchronisation in the kernel by preventing
     multiple threads from simultaneously executing critical sections of code
     accessing shared data.  A number of different locks are available:

     struct simplelock
              Provides a simple spinning mutex.  A processor will busy-wait
              while trying to acquire a simplelock.  The simplelock operations
              are implemented with machine-dependent locking primitives.

              Simplelocks are usually used only by the high-level lock manager
              and to protect short, critical sections of code.  Simplelocks
              are the only locks that can be be used inside an interrupt han-
              dler.  For a simplelock to be used in an interrupt handler, care
              must be taken to disable the interrupt, acquire the lock, do any
              processing, release the simplelock and re-enable the interrupt.
              This procedure is necessary to avoid deadlock between the inter-
              rupt handler and other threads executing on the same processor.

     struct lock
              Provides a high-level lock supporting sleeping/spinning until
              the lock can be acquired.  The lock manager supplies both exclu-
              sive-access and shared-access locks, with recursive exclusive-
              access locks within a single thread.  It also allows upgrading a
              shared-access lock to an exclusive-access lock, as well as down-
              grading an exclusive-access lock to a shared-access lock.

     If the kernel option LOCKDEBUG is enabled, additional facilities are pro-
     vided to record additional lock information.  These facilities are pro-
     vided to assist in determining deadlock occurrences.

FUNCTIONS
     The functions which operate on simplelocks are:

     simple_lock_init(slock)
              The simplelock slock is initialised to the unlocked state.  A
              statically allocated simplelock also can be initialised with the
              macro SIMPLELOCK_INITIALIZER.  The effect is the same as the dy-
              namic initialisation by a call to simple_lock_init.  For exam-
              ple,

              struct simplelock slock = SIMPLELOCK_INITIALIZER;

     simple_lock(slock)
              The simplelock slock is locked.  If the simplelock is held then
              execution will spin until the simplelock is acquired.  Care must
              be taken that the calling thread does not already hold the sim-
              plelock.  In this case, the simplelock can never be acquired.
              If kernel option LOCKDEBUG is enabled, a "locking against my-
              self" panic will occur.

     simple_lock_try(slock)
              Try to acquire the simplelock slock without spinning.  If the
              simplelock is held by another thread then the return value is 0.
              If the simplelock was acquired successfully then the return val-
              ue is 1.

     simple_lock_unlock(slock)
              The simplelock slock is unlocked.  The simplelock must be locked
              and the calling thread must be the one that last acquired the
              simplelock.  If the calling thread does not hold the simplelock,
              the simplelock will be released but the kernel behaviour is un-
              defined.

     simple_lock_freecheck(start, end)
              Check that all simplelocks in the address range start to end are
              not held.  If a simplelock within the range is found, the kernel
              enters the debugger.  This function is available only with ker-
              nel option LOCKDEBUG.  It provides a mechanism for basic simple-
              lock consistency checks.

     simple_lock_dump(void)
              Dump the state of all simplelocks in the kernel.  This function
              is available only with kernel option LOCKDEBUG.

     The functions which operate on locks are:

     lockinit(lock, prio, wmesg, timo, flags)
              The lock lock is initialised according to the parameters provid-
              ed.  Arguments are as follows:

              lock     The lock.

              prio     The thread priority when it is woken up after sleeping
                       on the lock.

              wmesg    A sleep message used when a thread goes to sleep wait-
                       ing for the lock, so that the exact reason it is sleep-
                       ing can easily be identified.

              timo     The maximum sleep time.  Used by tsleep(9).

              flags    Flags to specify the lock behaviour permanently over
                       the lifetime of the lock.  Valid lock flags are:

                       LK_NOWAIT
                                Threads should not sleep when attempting to
                                acquire the lock.

                       LK_SLEEPFAIL
                                Threads should sleep, then return failure when
                                acquiring the lock.

                       LK_CANRECURSE
                                Threads can acquire the lock recursively.

     lockmgr(lock, flags, slock)
              Set, change or release a lock according to the parameters pro-
              vided.  Arguments are as follows:

              lock     The lock.

              slock    Simplelock interlock.  If the flag LK_INTERLOCK is set
                       in flags, slock is a simplelock held by the caller.
                       When the lock lock is acquired, the simplelock is re-
                       leased.  If the flag LK_INTERLOCK is not set, slock is
                       ignored.

              flags    Flags to specify the lock request type.  In addition to
                       the flags specified above, the following flags are
                       valid:

                       LK_SHARED
                                Get one of many possible shared-access locks.
                                If a thread holding an exclusive-access lock
                                requests a shared-access lock, the exclusive-
                                access lock is downgraded to a shared-access
                                lock.

                       LK_EXCLUSIVE
                                Stop further shared-access locks, when they
                                are cleared, grant a pending upgrade if it ex-
                                ists, then grant an exclusive-access lock.
                                Only one exclusive-access lock may exist at a
                                time, except that a thread holding an exclu-
                                sive-access lock may get additional exclusive-
                                access locks if it explicitly sets the LK_CAN-
                                RECURSE flag in the lock request, or if the
                                LK_CANRECURSE flag was set when the lock was
                                initialised.

                       LK_UPGRADE
                                The thread must hold a shared-access lock that
                                it wants to have upgraded to an exclusive-ac-
                                cess lock.  Other threads may get exclusive
                                access to the protected resource between the
                                time that the upgrade is requested and the
                                time that it is granted.

                       LK_EXCLUPGRADE
                                The thread must hold a shared-access lock that
                                it wants to have upgraded to an exclusive-ac-
                                cess lock.  If the request succeeds, no other
                                threads will have acquired exclusive access to
                                the protected resource between the time that
                                the upgrade is requested and the time that it
                                is granted.  However, if another thread has
                                already requested an upgrade, the request will
                                fail.

                       LK_DOWNGRADE
                                The thread must hold an exclusive-access lock
                                that it wants to have downgraded to a shared-
                                access lock.  If the thread holds multiple
                                (recursive) exclusive-access locks, they will
                                all be downgraded to shared-access locks.

                       LK_RELEASE
                                Release one instance of a lock.

                       LK_DRAIN
                                Wait for all activity on the lock to end, then
                                mark it decommissioned.  This feature is used
                                before freeing a lock that is part of a piece
                                of memory that is about to be freed.

                       LK_REENABLE
                                Lock is to be re-enabled after drain.  The
                                LK_REENABLE flag may be set only at the re-
                                lease of a lock obtained by a drain.

                       LK_SETRECURSE
                                Other locks while we have it OK.

                       LK_RECURSEFAIL
                                Attempt at recursive lock fails.

                       LK_SPIN  Lock spins instead of sleeping.

                       LK_INTERLOCK
                                Unlock the simplelock slock when the lock is
                                acquired.

     lockstatus(lock)
              Determine the status of lock lock.  Returns LK_EXCLUSIVE or
              LK_SHARED for exclusive-access and shared-access locks respec-
              tively.

     lockmgr_printinfo(lock)
              Print out information about state of lock lock.

     spinlockinit(lock, wmesg, flags)
              The lock lock is initialised as a spinlock according to the pa-
              rameters provided.  Arguments are as follows:

              lock     The lock.

              wmesg    This is a simple name for lock.

              flags    Flags to specify the lock behaviour.  Valid lock flags
                       are the same as outlined above.

     spinlockmgr(lock, flags, slock)
              Set, change or release a lock according to the parameters pro-
              vided.  Arguments are as follows:

              lock     The spin lock.

              flags    Flags to specify the lock request type.  Valid lock
                       flags are the same as outlined above.

              slock    Simplelock interlock.  The simplelock slock is set by
                       the caller.  When the lock lock is acquired, the sim-
                       plelock is released.

RETURN VALUES
     Successfully acquired locks return 0.  A failed lock attempt always re-
     turns a non-zero error value.  No lock is held after an error return (in
     particular, a failed LK_UPGRADE or LK_FORCEUPGRADE will have released its
     shared-access lock).  Locks will always succeed unless one of the follow-
     ing is true:

     [EBUSY]       LK_FORCEUPGRADE is requested and some other thread has al-
                   ready requested a lock upgrade or LK_NOWAIT is set and a
                   sleep would be required.

     [ENOLCK]      LK_SLEEPFAIL is set and a sleep was done.

     [EINTR]       PCATCH is set in lock priority and a signal arrives to in-
                   terrupt a system call.

     [ERESTART]    PCATCH is set in lock priority and a signal arrives so that
                   the system call is restarted.

     [EWOULDBLOCK]
                   Non-null lock timeout and timeout expires.

CODE REFERENCES
     This section describes places within the NetBSD source tree where actual
     code implementing or utilising the locking framework can be found.  All
     pathnames are relative to /usr/src.

     The locking framework itself is implemented within the file
     sys/kern/kern_lock.c.  Data structures and function prototypes for the
     framework are located in sys/sys/lock.h.  Machine-dependent simplelock
     primitives are implemented within the file
     sys/arch/<arch>/include/lock.h.

SEE ALSO
     pmap(9), spl(9), tsleep(9), uvm(9)

HISTORY
     The kernel locking API first appeared in 4.4BSD-lite2.

NetBSD 1.6                       June 23, 2000                               5

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2014 Modified for NetBSD by Kimmo Suominen