A mutex
enforces a policy of mutual exclusion. Only one thread at a time may hold a particular mutex. Threads trying to lock a held mutex will block until the mutex is unlocked.
Mutexes are strictly bracketing and may not be recursively locked. That is to say, mutexes should be exited in the opposite order they were entered, and cannot be reentered before exiting.
mutex_init() initializes a mutex. It is an error to initialize a mutex more than once. The type argument should be set to MUTEX_DRIVER.
arg provides type-specific information for a given variant type of mutex. When mutex_init() is called for driver mutexes, if the mutex is used by the interrupt handler, the arg should be the ddi_iblock_cookie returned
from ddi_get_iblock_cookie(9F) or ddi_get_soft_iblock_cookie(9F). Note that arg should be the value of the iblock cookie casted to (void *), not the address of the cookie. The arguments passed to ddi_get_iblock_cookie(9F) and ddi_get_soft_iblock_cookie(9F), on the other hand, are the addresses of the cookie. If the mutex is
never used inside an interrupt handler, the argument should be NULL.
mutex_enter() is used to acquire a mutex. If the mutex is already held, then the caller blocks. After returning, the calling thread is the owner of the mutex. If the mutex is already held by the calling thread, a panic will ensue.
mutex_owned() should only be used in ASSERT() and may be enforced by not being defined unless the preprocessor symbol DEBUG is defined. Its return value is non-zero if the current thread (or,
if that cannot be determined, at least some thread) holds the mutex pointed to by mp.
mutex_tryenter() is very similar to mutex_enter() except that it doesn't block when the mutex is already held. mutex_tryenter() returns non-zero when it acquired the mutex and 0 when the mutex is already held.
mutex_exit() releases a mutex and will unblock another thread if any are blocked on the mutex.
mutex_destroy() releases any resources that might have been allocated by mutex_init(). mutex_destroy() must be called before freeing the memory containing the mutex, and should be called with the mutex unheld (not owned by any thread). The
caller must somehow be sure that no other thread will attempt to use the mutex.
|