groovyx.gpars.agent
Class AgentBase<T>

java.lang.Object
  groovyx.gpars.agent.AgentCore
      groovyx.gpars.agent.AgentBase<T>

Direct Known Subclasses:

Agent

abstract class AgentBase<T>
extends AgentCore

Implements most of Agent's public method in Java

Author:

Vaclav Pech

Nested Class Summary

private static class

AgentBase.AwaitClosure Returns the current value of the Agent's state

Field Summary

private static groovy.lang.Closure	awaitClosure
private groovy.lang.Closure	copy Function converting the internal state during read to prevent internal state escape from the protected boundary of the agent
protected T	data Holds the internal mutable state
private java.util.Collection<groovy.lang.Closure>	listeners Holds all listeners interested in state updates A listener should be a closure accepting the old and the new value in this order.
protected java.util.concurrent.locks.ReadWriteLock	lock Allows reads not to wait in the message queue.
private java.util.Collection<groovy.lang.Closure>	validators Holds all validators checking the agent's state A validator should be a closure accepting the old and the new value in this order.

Constructor Summary

AgentBase(T data)

AgentBase(T data, groovy.lang.Closure copy)
Creates a new Agent around the supplied modifiable object

Method Summary

void	addListener(groovy.lang.Closure listener) Adds a listener interested in state updates A listener should be a closure accepting the old and the new value in this order plus optionally the agent reference as the first argument.
void	addValidator(groovy.lang.Closure validator) Adds a validator checking the agent's state A listener should be a closure accepting the old and the new value in this order plus optionally the agent reference as the first argument.
void	await() Blocks until all messages in the queue prior to call to await() complete.
T	getInstantVal() A shorthand method for safe message-based retrieval of the internal state.
T	getVal() A shorthand method for safe message-based retrieval of the internal state.
private groovy.lang.Closure	checkClosure(groovy.lang.Closure code) Only two-argument closures are allowed
(package private) void	onMessage(groovy.lang.Closure code) Accepts and invokes the closure
(package private) void	onMessage(org.codehaus.groovy.runtime.NullObject obj) Accepts a NullObject instance and sets the internal state to null
(package private) void	onMessage(T message) Other messages than closures are accepted as new values for the internal state
(package private) T	sendAndWait(groovy.lang.Closure message) Submits the closure waiting for the result
void	updateValue(T newValue) Allows closures to set the new internal state as a whole Do not call this method directly from the outside.
void	valAsync(groovy.lang.Closure callback) A shorthand method for safe asynchronous message-based retrieval of the internal state.

Methods inherited from class groovyx.gpars.agent.AgentCore

attachToThreadPool, call, getErrors, handleMessage, hasErrors, isFair, leftShift, makeFair, registerError, send, setPGroup

Methods inherited from class java.lang.Object

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

Field Detail

lock

protected java.util.concurrent.locks.ReadWriteLock lock

Allows reads not to wait in the message queue. Writes and reads are mutually separated by using write or read locks respectively.

data

protected T data

Holds the internal mutable state

copy

private final groovy.lang.Closure copy

Function converting the internal state during read to prevent internal state escape from the protected boundary of the agent

listeners

private final java.util.Collection<groovy.lang.Closure> listeners

Holds all listeners interested in state updates A listener should be a closure accepting the old and the new value in this order.

validators

private final java.util.Collection<groovy.lang.Closure> validators

Holds all validators checking the agent's state A validator should be a closure accepting the old and the new value in this order.

awaitClosure

private static final groovy.lang.Closure awaitClosure

Constructor Detail

AgentBase

AgentBase(T data)

AgentBase

AgentBase(T data,
          groovy.lang.Closure copy)

Creates a new Agent around the supplied modifiable object

Parameters:

data - The object to use for storing the internal state of the variable

copy - A closure to use to create a copy of the internal state when sending the internal state out

Method Detail

onMessage

final void onMessage(org.codehaus.groovy.runtime.NullObject obj)

Accepts a NullObject instance and sets the internal state to null

Parameters:

obj - The received message

onMessage

final void onMessage(groovy.lang.Closure code)

Accepts and invokes the closure

Parameters:

code - The received message

onMessage

final void onMessage(T message)

Other messages than closures are accepted as new values for the internal state

Parameters:

message - The received message

updateValue

public final void updateValue(T newValue)

Allows closures to set the new internal state as a whole Do not call this method directly from the outside. It is designed to be used from within the submitted closures.

Parameters:

newValue - The value to set the internal state to

getInstantVal

public final T getInstantVal()

A shorthand method for safe message-based retrieval of the internal state. Retrieves the internal state immediately by-passing the queue of tasks waiting to be processed.

Returns:

The current value of the actor's state

getVal

public final T getVal()
               throws java.lang.InterruptedException

A shorthand method for safe message-based retrieval of the internal state. The request to retrieve a value is put into the message queue, so will wait for all messages delivered earlier to complete.

Returns:

The value of the actor's state once all previously sent messages in the queue get processed

Throws:

java.lang.InterruptedException - If the thread gets interrupted while waiting for a value to be bound

valAsync

public final void valAsync(groovy.lang.Closure callback)

A shorthand method for safe asynchronous message-based retrieval of the internal state. The request to retrieve a value is put into the message queue, so will wait for all messages delivered earlier to complete.

Parameters:

callback - A closure to invoke with the internal state as a parameter

sendAndWait

final T sendAndWait(groovy.lang.Closure message)
             throws java.lang.InterruptedException

Submits the closure waiting for the result

Parameters:

message - The message/closure to send

Returns:

The return value of the closure

Throws:

java.lang.InterruptedException - If the thread gets interrupted while waiting for a value to be bound

await

public final void await()
                 throws java.lang.InterruptedException

Blocks until all messages in the queue prior to call to await() complete. Provides a means to synchronize with the Agent

Throws:

java.lang.InterruptedException - If the thread gets interrupted while waiting for a value to be bound

addListener

public void addListener(groovy.lang.Closure listener)

Adds a listener interested in state updates A listener should be a closure accepting the old and the new value in this order plus optionally the agent reference as the first argument.

Parameters:

listener - The closure with two or three arguments

addValidator

public void addValidator(groovy.lang.Closure validator)

Adds a validator checking the agent's state A listener should be a closure accepting the old and the new value in this order plus optionally the agent reference as the first argument.

Parameters:

validator - The closure with two or three arguments

checkClosure

private groovy.lang.Closure checkClosure(groovy.lang.Closure code)

Only two-argument closures are allowed

Parameters:

code - The passed-in closure

Returns:

Either the original closure or a two-argument closure after currying the first argument of the passed-in closure to self