7.7.1.1 User-defined Mutexes

 One of the simplest and most powerful primitives for thread synchronization are mutexes. The mutexes provided by the following primitives are recursive: if a thread $T$ locks a recursive mutex $M$, any calls to mutex_lock(M) made by $T$ will immediately succeed without suspending while $M$ is locked. Other threads that attempt to lock $M$ will suspend until $M$ is unlocked. To unlock $M$ after $n$ calls to mutex_lock(M), $T$ must make $n$ calls to mutex_unlock(M).

When using mutexes in XSB, programmers must not only avoid explicitly creating deadlocks, but must also ensure that a mutex is unlocked when leaving a critical area, and destroyed when it is no longer needed. Making sure that this happens for successful goals, for failed goals and for goals that raise exceptions can sometimes be complicated. The predicate with_mutex/2 handles all of these cases. We recommend using it if possible, and making use of lower-level calls to mutex_lock/1, mutex_unlock/1 and mutex_trylock/1 only when with_mutex/2 is not applicable.

with_mutex(+Mutex,?Goal)

mutex_xsb
Locks a current mutex or aliasMutex, executes Goal deterministically, then unlocks Mutex. If Goal leaves choice-points, these are destroyed. Mutex is unlocked regardless of whether Goal succeeds, fails or raises an exception. Any exception thrown by Goal is re-thrown after the mutex has been successfully unlocked.

Error Cases

• Mutex is a variable
  • instantiation_error
• Mutex is not a mutex id or alias
  • domain_error(mutex_or_alias,Mutex_or_Alias)
• Mutex is not associated with a current mutex.
  • existence_error(mutex,Mutex)
• Locking Mutex would give rise to a deadlock ^7.5
  • permission_error(mutex,lock,Mutex)
• Goal is a variable
  • instantiation error
• Goal is neither a variable nor a callable term
  • type error(callable, Goal)

mutex_create(?Mutex)

mutex_xsb
Creates a new recursive user mutex with identifier Mutex. Options allows optional parameters to be passed, currently only for aliases of the mutex.

• alias(Mutex): Allow queue Mutex to be referred to via Mutex in all standard queue predicates. Mutex remains active for Mutex until it is destroyed.

Error Cases

• Mutex is not a variable
  • type_error(variable,Mutex)
• Options is a partial list or a list with an element that is a variable
  • instantiation error
• Options is neither a partial list or a list
  • type error(list, Options)
• Options contains an option, Option not described above
  • domain_error(mutex_option,Option)
• An element of Options is alias(A) and A is already associated with an existing thread, queue, mutex or stream
  • permission_error(create,alias, A)
• An element of Options is alias(A) and A is not an atom
  • type_error(atom,A)

mutex_destroy(+Mutex)

mutex_xsb
Destroys a current unlocked mutex with alias or id Mutex along with any memory it uses.

Error Cases

• Mutex is a variable
  • instantiation_error
• Mutex is not a mutex id or alias
  • domain_error(mutex_or_alias,Mutex_or_Alias)
• Mutex is not associated with a current mutex.
  • existence_error(mutex,Mutex)
• Mutex is locked
  • permission_error(mutex,destroy,Mutex)

mutex_lock(+Mutex)

mutex_xsb
mutex_lock(Mutex) locks a (recursive) mutex with alias or id Mutex. Locking and unlocking mutexes should be paired carefully in order to avoid deadlocks. In particular, a programmer needs to ensure that mutexes are properly unlocked even if the protected code fails or raises an exception.

Error Cases

• Mutex is a variable
  • instantiation_error
• Mutex is not a mutex id or alias
  • domain_error(mutex_or_alias,Mutex_or_Alias)
• Mutex is not associated with a current mutex.
  • existence_error(mutex,Mutex)
• Locking Mutex would give rise to a deadlock ^7.6
  • permission_error(mutex,lock,Mutex)

mutex_trylock(+Mutex)

mutex_xsb
Works as mutex_lock/1 but fails immediately if Mutex is held by another thread, rather than suspending the calling thread.

Error Cases

• Mutex is a variable
  • instantiation_error
• Mutex is not a mutex id or alias
  • domain_error(mutex_or_alias,Mutex_or_Alias)
• Mutex is not associated with a current mutex.
  • existence_error(mutex,Mutex)

mutex_unlock(+Mutex)

mutex_xsb
Unlocks the mutex with alias or id Mutex when called by the same thread that locked Mutex.

Error Cases

• Mutex is a variable
  • instantiation_error
• Mutex is not a mutex id or alias
  • domain_error(mutex_or_alias,Mutex_or_Alias)
• Mutex is not associated with a current mutex.
  • existence_error(mutex,Mutex)
• Mutex is not held by the calling thread
  • permission_error(unlock,mutex,Mutex)

mutex_unlock_all

mutex_xsb
mutex_unlock_all/0 unlocks all user mutexes owned by the current thread. It has no error cases.

mutex_property(?Mutex,?Property)

mutex_xsb
If Mutex is instantiated, unifies Property with current properties of the mutex; if Mutex is a variable, backtracks through all the current mutexes whose properties unify with Property. If the mutex is locked, Property will be a term of the form locked(ThreadId,NumLocks) where ThreadId is a thread id, and NumLocks is the number of times the mutex has been locked. If the mutex is unlocked, Property will be a term of the form unlocked(NumLocks) where NumLocks is the number of times the mutex has been locked.

Error Cases

• Mutex is not an atom
  • type_error(atom,Mutex)