Class Mutex

Read-many/write-one lock.
Allows control over resources that
can be read by several readers at once but only written by one writer.

It is guaranteed that if you are a writer you can also enter the
mutex as a reader. Conversely, if you are the only reader you
can enter the mutex as a writer, but you'll be warned because it is very
deadlock prone (two readers trying to get write access concurently).

If the mutex is used only by one thread, the thread can repeatedly
enter it as a writer or reader. So one thread can never deadlock itself,
whichever order operations are performed in.

There is no strategy to prevent starvation.
Even if there is a writer waiting to enter, another reader might enter
the section instead.

Mutex

Constructor for those who wish to do some custom additional tasks
whenever an action or runnable is executed in the Mutex. This
may be useful for wrapping all the actions with custom ThreadLocal
value, etc. Just implement the Executor's execute(Runnable)
method and do pre and post initialization tasks before running the runnable.

readAccess

Run an action with read access and possibly throw a checked exception.
The exception if thrown is then encapsulated
in a MutexException and thrown from this method. One is encouraged
to catch MutexException, obtain the inner exception, and rethrow it.
Here is an example:

isReadAccess

public boolean isReadAccess()

Tests whether this thread has already entered the mutex in read access.
If it returns true, calling readAccess
will be executed immediatelly
without any blocking.
Calling postWriteAccess will delay the execution
of its Runnable until a readAccess section is over
and calling writeAccess is strongly prohibited and will
result in a warning as a deadlock prone behaviour.

Warning: since a thread with write access automatically
has effective read access as well (whether or not explicitly requested), if
you want to check whether a thread can read some data, you should check for
either kind of access, e.g.:

assert myMutex.isReadAccess() || myMutex.isWriteAccess();

Returns:

true if the thread is in read access section

Since:

4.48

isWriteAccess

public boolean isWriteAccess()

Tests whether this thread has already entered the mutex in write access.
If it returns true, calling writeAccess will be executed
immediatelly without any other blocking. postReadAccess
will be delayed until a write access runnable is over.

Returns:

true if the thread is in write access section

Since:

4.48

toString

postReadRequest

Posts a read request. This request runs immediately iff
this SimpleMutex is in the shared mode or this SimpleMutex is not contended
at all.
This request is delayed if this SimpleMutex is in the exclusive
mode and is held by this thread, until the exclusive is left.
Finally, this request blocks, if this SimpleMutex is in the exclusive
mode and is held by another thread.

Warning: this method blocks.

Parameters:

run - runnable to run

postWriteRequest

Posts a write request. This request runs immediately iff
this SimpleMutex is in the "pure" exclusive mode, i.e. this SimpleMutex
is not reentered in shared mode after the exclusive mode
was acquired. Otherwise it is delayed until all read requests
are executed.
This request runs immediately if this SimpleMutex is not contended at all.
This request blocks if this SimpleMutex is in the shared mode.