table of contents
|LOCK(9)||Kernel Developer's Manual||LOCK(9)|
lockmgr family of functions
lockinit(struct lock *lkp, int prio, const char *wmesg, int timo, int flags); void
lockdestroy(struct lock *lkp); int
lockmgr(struct lock *lkp, u_int flags, struct mtx *ilk); int
lockmgr_args(struct lock *lkp, u_int flags, struct mtx *ilk, const char *wmesg, int prio, int timo); int
lockmgr_args_rw(struct lock *lkp, u_int flags, struct rwlock *ilk, const char *wmesg, int prio, int timo); void
lockmgr_disown(struct lock *lkp); void
lockmgr_printinfo(const struct lock *lkp); int
lockmgr_recursed(const struct lock *lkp); int
lockmgr_rw(struct lock *lkp, u_int flags, struct rwlock *ilk); int
lockmgr_waiters(const struct lock *lkp); int
lockstatus(const struct lock *lkp);
lockmgr_assert(const struct lock *lkp, int what);
lockinit() function is used to initialize a lock. It must be called before any operation can be performed on a lock. Its arguments are:
- A pointer to the lock to initialize.
- The priority passed to sleep(9).
- The lock message. This is used for both debugging output and sleep(9).
- The timeout value passed to sleep(9).
- The flags the lock is to be initialized with:
- Enable adaptive spinning for this lock if the kernel is compiled with the ADAPTIVE_LOCKMGRS option.
- Allow recursive exclusive locks.
- Disable lock profiling for this lock.
- Allow exclusive locks only.
- Instruct witness(4) to ignore this lock.
- witness(4) should log messages about duplicate locks being acquired.
- Disable ktr(4) logging for this lock.
- Use timo during a sleep; otherwise, 0 is used.
lockdestroy() function is used to destroy a lock, and while it is called in a number of places in the kernel, it currently does nothing. The
lockmgr_rw() functions handle general locking functionality within the kernel, including support for shared and exclusive locks, and recursion.
lockmgr_rw() are also able to upgrade and downgrade locks. Their arguments are:
- A pointer to the lock to manipulate.
- Flags indicating what action is to be taken.
- Acquire a shared lock. If an exclusive lock is currently held,
EDEADLKwill be returned.
- Acquire an exclusive lock. If an exclusive lock is already held, and
LK_CANRECURSEis not set, the system will panic(9).
- Downgrade exclusive lock to a shared lock. Downgrading a shared lock is not permitted. If an exclusive lock has been recursed, the system will panic(9).
- Upgrade a shared lock to an exclusive lock. If this call fails, the
shared lock is lost, even if the
LK_NOWAITflag is specified. During the upgrade, the shared lock could be temporarily dropped. Attempts to upgrade an exclusive lock will cause a panic(9).
- Try to upgrade a shared lock to an exclusive lock. The failure to upgrade does not result in the dropping of the shared lock ownership.
- Release the lock. Releasing a lock that is not held can cause a panic(9).
- Wait for all activity on the lock to end, then mark it decommissioned.
This is used before freeing a lock that is part of a piece of memory
that is about to be freed. (As documented in
- Fail if operation has slept.
- Do not allow the call to sleep. This can be used to test the lock.
- Skip the witness(4) checks for this instance.
- Allow recursion on an exclusive lock. For every lock there must be a release.
- Unlock the interlock (which should be locked already).
- An interlock mutex for controlling group access to the lock. If
lockmgr_rw() assume ilk is currently owned and not recursed, and will return it unlocked. See mtx_assert(9).
lockmgr_args_rw() function work like
lockmgr_rw() but accepting a wmesg, timo and prio on a per-instance basis. The specified values will override the default ones, but this can still be used passing, respectively,
lockmgr_disown() function switches the owner from the current thread to be
LK_KERNPROC, if the lock is already held. The
lockmgr_printinfo() function prints debugging information about the lock. It is used primarily by VOP_PRINT(9) functions. The
lockmgr_recursed() function returns true if the lock is recursed, 0 otherwise. The
lockmgr_waiters() function returns true if the lock has waiters, 0 otherwise. The
lockstatus() function returns the status of the lock in relation to the current thread. When compiled with
options INVARIANT_SUPPORT, the
lockmgr_assert() function tests lkp for the assertions specified in what, and panics if they are not met. One of the following assertions must be specified:
- Assert that the current thread has either a shared or an exclusive lock on the lkp lock pointed to by the first argument.
- Assert that the current thread has a shared lock on the lkp lock pointed to by the first argument.
- Assert that the current thread has an exclusive lock on the lkp lock pointed to by the first argument.
- Assert that the current thread has no lock on the lkp lock pointed to by the first argument.
- Assert that the current thread has a recursed lock on lkp.
- Assert that the current thread does not have a recursed lock on lkp.
lockmgr_rw() functions return 0 on success and non-zero on failure. The
lockstatus() function returns:
- An exclusive lock is held by the current thread.
- An exclusive lock is held by someone other than the current thread.
- A shared lock is held.
- The lock is not held by anyone.
lockmgr_rw() fail if:
LK_FORCEUPGRADEwas requested and another thread had already requested a lock upgrade.
LK_NOWAITwas set, and a sleep would have been required, or
LK_TRYUPGRADEoperation was not able to upgrade the lock.
LK_SLEEPFAILwas set and
lockmgr_rw() did sleep.
PCATCHwas set in the lock priority, and a signal was delivered during a sleep. Note the
PCATCHwas set in the lock priority, a signal was delivered during a sleep, and the system call is to be restarted.
- a non-zero timeout was given, and the timeout expired.
LK_INTERLOCKis passed in the flags argument to
lockmgr_rw(), the ilk must be held prior to calling
lockmgr_rw(), and will be returned unlocked. Upgrade attempts that fail result in the loss of the lock that is currently held. Also, it is invalid to upgrade an exclusive lock, and a panic(9) will be the result of trying.
SEE ALSO¶condvar(9), locking(9), mutex(9), rwlock(9), sleep(9), sx(9), mtx_assert(9), panic(9), VOP_PRINT(9)
AUTHORS¶This manual page was written by Chad David ⟨email@example.com⟩.
|October 6, 2013||Debian|