kotlinx.coroutines.sync

Interface Mutex

public Mutex

Mutual exclusion for coroutines.

Mutex has two states: locked and unlocked. It is non-reentrant, that is invoking Mutex.lock even from the same thread/coroutine that currently holds the lock still suspends the invoker.

JVM API note: Memory semantic of the interface Mutex is similar to synchronized block on JVM: An unlock on a interface Mutex happens-before every subsequent successful lock on that interface Mutex. Unsuccessful call to Mutex.tryLock do not have any memory effects.

See Also:

Mutex.lock, interface Mutex, interface Mutex, interface Mutex, Mutex.tryLock

Method Summary

Modifier and Type	Method and Description
SelectClause2<java.lang.Object,kotlinx.coroutines.sync.Mutex>	getOnLock() Clause for select expression of Mutex.lock suspending function that selects when the mutex is locked. Additional parameter for the clause in the owner (see Mutex.lock) and when the clause is selected the reference to this mutex is passed into the corresponding block.
boolean	holdsLock(java.lang.Object owner) Checks mutex locked by owner
boolean	isLocked() Returns true when this mutex is locked.
java.lang.Object	lock(java.lang.Object owner, kotlin.coroutines.experimental.Continuation<? super kotlin.Unit> p) Locks this mutex, suspending caller while the mutex is locked.
boolean	tryLock(java.lang.Object owner) Tries to lock this mutex, returning false if this mutex is already locked.
void	unlock(java.lang.Object owner) Unlocks this mutex. Throws IllegalStateException if invoked on a mutex that is not locked or was locked with a different owner token (by identity).

Method Detail

isLocked

boolean isLocked()

Returns true when this mutex is locked.

tryLock

boolean tryLock(java.lang.Object owner)

Tries to lock this mutex, returning false if this mutex is already locked.

Parameters:

owner - Optional owner token for debugging. When owner is specified (non-null value) and this mutex is already locked with the same token (same identity), this function throws IllegalStateException.

lock

java.lang.Object lock(java.lang.Object owner,
                      kotlin.coroutines.experimental.Continuation<? super kotlin.Unit> p)

Locks this mutex, suspending caller while the mutex is locked.

This suspending function is cancellable. If the interface Job of the current coroutine is cancelled or completed while this function is suspended, this function immediately resumes with CancellationException.

Cancellation of suspended lock invocation is atomic -- when this function throws CancellationException it means that the mutex was not locked. As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may continue to execute even after it was cancelled from the same thread in the case when this lock operation was already resumed and the continuation was posted for execution to the thread's queue.

Note, that this function does not check for cancellation when it is not suspended. Use YieldKt.yield or CoroutineScopeKt.isActive to periodically check for cancellation in tight loops if needed.

This function can be used in select invocation with Mutex.getOnLock clause. Use Mutex.tryLock to try acquire lock without waiting.

This function is fair; suspended callers are resumed in first-in-first-out order.

Parameters:

owner - Optional owner token for debugging. When owner is specified (non-null value) and this mutex is already locked with the same token (same identity), this function throws IllegalStateException.

See Also:

interface Job, YieldKt.yield, CoroutineScopeKt.isActive, Mutex.getOnLock, Mutex.tryLock

getOnLock

SelectClause2<java.lang.Object,kotlinx.coroutines.sync.Mutex> getOnLock()

Clause for select expression of Mutex.lock suspending function that selects when the mutex is locked. Additional parameter for the clause in the owner (see Mutex.lock) and when the clause is selected the reference to this mutex is passed into the corresponding block.

See Also:

Mutex.lock, Mutex.lock

holdsLock

boolean holdsLock(java.lang.Object owner)

Checks mutex locked by owner

Returns:

true on mutex lock by owner, false if not locker or it is locked by different owner

unlock

void unlock(java.lang.Object owner)

Unlocks this mutex. Throws IllegalStateException if invoked on a mutex that is not locked or was locked with a different owner token (by identity).

Parameters:

owner - Optional owner token for debugging. When owner is specified (non-null value) and this mutex was locked with the different token (by identity), this function throws IllegalStateException.

See Also:

IllegalStateException