abstract suspend fun lock(owner: Any? = null): Unit (source)

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

This suspending function is cancellable. If the 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 yield or CoroutineScope.isActive to periodically check for cancellation in tight loops if needed.

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

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


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.