Package com.github.vfro

Class Monitor<Entity>

java.lang.Object

com.github.vfro.Monitor<Entity>

Type Parameters:

Entity - monitored entity type.

public class Monitor<Entity>
extends Object

Monitor is a synchronization construct that allows threads to have both thread-safe access to underlying monitored object or value (hereinafter monitored entity) and wait for it to mutate (if it is a mutable object) or change (if it is an immutable value) to a desirable state.

 Monitor<Queue<String>> outputQueue =
    new Monitor<>(new LinkedList<String>());

 // ... monitoring thread
 while(true) {
    // wait for a new string in queue
    outputQueue.write(
       queue -> {
             System.out.println(queue.pull());

             // write access lambda must return its argument
             // to preserve reference to the queue
             return queue;
          },

       // wake up when the queue is not empty
       queue -> !queue.isEmpty()
    );
 }

 // ... somewhere in some other thread
 outputQueue.write(
    queue -> {
          queue.add("Hello Monitor!");
          return queue;
       }
 );
 

Constructor Summary

Constructors

Modifier	Constructor	Description
	Monitor(Entity entity)	Create new instance of Monitor initialized by monitored entity.
protected	Monitor(Entity entity, Lock readLock, Lock writeLock)	Create new instance of Monitor initialized by an entity and custom locks.

Method Summary

Modifier and Type	Method	Description
protected Condition	getCondition()	Get a condition variable which is signaled after mutation or change of monitored entity.
protected Entity	getEntity()	Get access to monitored entity without any synchronization.
protected Lock	getReadLock()	Get a lock which is used for shared access.
protected Lock	getWriteLock()	Get lock which is used for exclusive access.
void	read(Consumer<Entity> consumer)	Access monitored entity in shared mode.
void	read(Consumer<Entity> consumer, Predicate<Entity> predicate)	Wait for monitored entity to mutate or change to a desirable state and access it in shared mode.
boolean	read(Consumer<Entity> consumer, Predicate<Entity> predicate, long time, TimeUnit unit)	Wait for monitored entity to mutate or change to a desirable state and access it in shared mode.
void	set(Entity entity)	Change monitored entity.
protected void	setEntity(Entity entity)	Modify monitored entity directly without any synchronization.
Entity	swap(Entity entity)	Change monitored entity and return the previous value.
void	write(UnaryOperator<Entity> operator)	Access monitored entity in exclusive mode.
void	write(UnaryOperator<Entity> operator, Predicate<Entity> predicate)	Wait for monitored entity to mutate or change to a desirable state and access it in exclusive mode.
boolean	write(UnaryOperator<Entity> operator, Predicate<Entity> predicate, long time, TimeUnit unit)	Wait for monitored entity to mutate or change to a desirable state and access it in exclusive mode.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Monitor

public Monitor(Entity entity)

Create new instance of Monitor initialized by monitored entity.

Parameters:

entity - monitored entity.

Monitor

protected Monitor(Entity entity,
                  Lock readLock,
                  Lock writeLock)

Create new instance of Monitor initialized by an entity and custom locks. Custom locks must be re-entrant and support lock downgrading (Acquiring read lock inside write lock, and release write lock after that).

Parameters:

entity - monitored entity.

readLock - Custom read lock.

writeLock - Custom write lock. It may be the same instance as readLock.

See Also:

ReentrantReadWriteLock

Method Detail

getEntity

protected Entity getEntity()

Get access to monitored entity without any synchronization.

Returns:

the monitored entity.

See Also:

setEntity(java.lang.Object)

setEntity

protected void setEntity(Entity entity)

Modify monitored entity directly without any synchronization.

Parameters:

entity - the new monitored entity.

See Also:

set(java.lang.Object), getEntity()

getReadLock

protected final Lock getReadLock()

Get a lock which is used for shared access.

Returns:

read access lock.

See Also:

getWriteLock()

getWriteLock

protected final Lock getWriteLock()

Get lock which is used for exclusive access.

Returns:

write access lock.

See Also:

getReadLock()

getCondition

protected final Condition getCondition()

Get a condition variable which is signaled after mutation or change of monitored entity.

Returns:

condition variable.

read

public final void read(Consumer<Entity> consumer)

Access monitored entity in shared mode.

Parameters:

consumer - access monitored entity. The consumer must not mutate monitored entity.

See Also:

read(java.util.function.Consumer, java.util.function.Predicate), read(java.util.function.Consumer, java.util.function.Predicate, long, java.util.concurrent.TimeUnit)

read

public final void read(Consumer<Entity> consumer,
                       Predicate<Entity> predicate)
                throws InterruptedException

Wait for monitored entity to mutate or change to a desirable state and access it in shared mode.

Parameters:

consumer - access monitored entity. The consumer must not mutate monitored entity.

predicate - a desirable state.

Throws:

InterruptedException - if the current thread is interrupted.

See Also:

read(java.util.function.Consumer), read(java.util.function.Consumer, java.util.function.Predicate, long, java.util.concurrent.TimeUnit)

read

public final boolean read(Consumer<Entity> consumer,
                          Predicate<Entity> predicate,
                          long time,
                          TimeUnit unit)
                   throws InterruptedException

Wait for monitored entity to mutate or change to a desirable state and access it in shared mode.

Parameters:

consumer - access monitored entity. The consumer must not mutate monitored entity.

predicate - a desirable state.

time - the maximum time to wait.

unit - the time unit of the time argument.

Returns:

true if the monitored entity has been accessed or false if the waiting time detectably elapsed before return from the method.

Throws:

InterruptedException - if the current thread is interrupted.

See Also:

read(java.util.function.Consumer), read(java.util.function.Consumer, java.util.function.Predicate)

write

public final void write(UnaryOperator<Entity> operator)

Access monitored entity in exclusive mode. Return value of operator becomes new monitored entity.

Parameters:

operator - exclusively access monitored entity. The operator may mutate monitored entity or replace it with a new one.

See Also:

write(java.util.function.UnaryOperator, java.util.function.Predicate), write(java.util.function.UnaryOperator, java.util.function.Predicate, long, java.util.concurrent.TimeUnit)

write

public final void write(UnaryOperator<Entity> operator,
                        Predicate<Entity> predicate)
                 throws InterruptedException

Wait for monitored entity to mutate or change to a desirable state and access it in exclusive mode. Return value of operator becomes new monitored entity.

Parameters:

operator - exclusively access monitored entity. The operator may mutate monitored entity or replace it with a new one.

predicate - a desirable state.

Throws:

InterruptedException - if the current thread is interrupted.

See Also:

write(java.util.function.UnaryOperator), write(java.util.function.UnaryOperator, java.util.function.Predicate, long, java.util.concurrent.TimeUnit)

write

public final boolean write(UnaryOperator<Entity> operator,
                           Predicate<Entity> predicate,
                           long time,
                           TimeUnit unit)
                    throws InterruptedException

Wait for monitored entity to mutate or change to a desirable state and access it in exclusive mode. Return value of operator becomes new monitored entity.

Parameters:

operator - exclusively access monitored entity. The operator may mutate monitored entity or replace it with a new one.

predicate - a desirable state.

time - the maximum time to wait.

unit - the time unit of the time argument.

Returns:

true if the monitored entity has been accessed or false if the waiting time detectably elapsed before return from the method.

Throws:

InterruptedException - if the current thread is interrupted.

See Also:

write(java.util.function.UnaryOperator), write(java.util.function.UnaryOperator, java.util.function.Predicate)

set

public final void set(Entity entity)

Change monitored entity.

Parameters:

entity - new monitored entity.

See Also:

swap(java.lang.Object)

swap

public final Entity swap(Entity entity)

Change monitored entity and return the previous value.

Parameters:

entity - new monitored entity.

Returns:

previous monitored entity.

See Also:

set(java.lang.Object)