Groovy Documentation

gpars.agent
Class Agent

java.lang.Object
  gpars.agent.AgentCore
      gpars.agent.Agent

class Agent
extends AgentCore

A special-purpose thread-safe non-blocking reference implementation inspired by Agents in Clojure. Agents safe-guard mutable values by allowing only a single agent-managed thread to make modifications to them. The mutable values are not directly accessible from outside, but instead requests have to be sent to the agent and the agent guarantees to process the requests sequentially on behalf of the callers. Agents guarantee sequential execution of all requests and so consistency of the values. An agent wraps a reference to mutable state, held inside a single field, and accepts code (closures / commands) as messages, which can be sent to the Agent just like to any other actor using the '<<' operator or any of the send() methods. After reception of a closure / command, the closure is invoked against the internal mutable field. The closure is guaranteed to be run without intervention from other threads and so may freely alter the internal state of the Agent held in the internal data field. The return value of the submitted closure is sent in reply to the sender of the closure. If the message sent to an agent is not a closure, it is considered to be a new value for the internal reference field. The internal reference can also be changed using the updateValue() method from within the received closures. The 'val' property of an agent will safely return the current value of the Agent, while the valAsync() method will do the same without blocking the caller. The 'instantVal' property will retrieve the current value of the Agent without having to wait in the queue of tasks. The initial internal value can be passed to the constructor. The two-parameter constructor allows to alter the way the internal value is returned from val/valAsync. By default the original reference is returned, but in many scenarios a copy or a clone might be more appropriate.

author:
Vaclav Pech Date: Jul 2, 2009


Property Summary
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

 
Constructor Summary
Agent()

Creates a new Agent with the internal state set to null

Agent(T data)

Creates a new Agent around the supplied modifiable object

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

Creates a new Agent around the supplied modifiable object

 
Method Summary
static Agent agent(def state)

Creates an agent instance initialized with the given state.

static Agent agent(def state, groovy.lang.Closure copy)

Creates an agent instance initialized with the given state.

void await()

Blocks until all messages in the queue prior to call to await() complete.

static Agent fairAgent(def state)

Creates an agent instance initialized with the given state, which will cooperate in thread sharing with other Agent instances in a fair manner.

static Agent fairAgent(def state, groovy.lang.Closure copy)

Creates an agent instance initialized with the given state, which will cooperate in thread sharing with other Agent instances in a fair manner.

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.

void handleMessage(Object message)

Dynamically dispatches the method call

void onMessage(NullObject obj)

Accepts a NullObject instance and sets the internal state to null

void onMessage(groovy.lang.Closure code)

Accepts and invokes the closure

void onMessage(T message)

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

def 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

void valAsync(groovy.lang.Closure callback)

A shorthand method for safe asynchronous message-based retrieval of the internal state.

 
Methods inherited from class AgentCore
attachToThreadPool, call, getErrors, getThreadPool, handleMessage, isFair, leftShift, makeFair, run, schedule, send, setPGroup
 

Property Detail

copy

final groovy.lang.Closure copy
Function converting the internal state during read to prevent internal state escape from the protected boundary of the agent


data

protected T data
Holds the internal mutable state


 
Constructor Detail

Agent

public Agent()
Creates a new Agent with the internal state set to null


Agent

public Agent(T data)
Creates a new Agent around the supplied modifiable object
param:
data The object to use for storing the internal state of the variable


Agent

public Agent(T data, groovy.lang.Closure copy)
Creates a new Agent around the supplied modifiable object
param:
data The object to use for storing the internal state of the variable
param:
copy A closure to use to create a copy of the internal state when sending the internal state out


 
Method Detail

agent

public static final Agent agent(def state)
Creates an agent instance initialized with the given state. The instance will use the default thread pool.
param:
state The initial internal state of the new Agent instance
return:
The created instance


agent

public static final Agent agent(def state, groovy.lang.Closure copy)
Creates an agent instance initialized with the given state. The instance will use the default thread pool.
param:
state The initial internal state of the new Agent instance
param:
copy A closure to use to create a copy of the internal state when sending the internal state out
return:
The created instance


await

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


fairAgent

public static final Agent fairAgent(def state)
Creates an agent instance initialized with the given state, which will cooperate in thread sharing with other Agent instances in a fair manner. The instance will use the default thread pool.
param:
state The initial internal state of the new Agent instance
return:
The created instance


fairAgent

public static final Agent fairAgent(def state, groovy.lang.Closure copy)
Creates an agent instance initialized with the given state, which will cooperate in thread sharing with other Agent instances in a fair manner. The instance will use the default thread pool.
param:
state The initial internal state of the new Agent instance
param:
copy A closure to use to create a copy of the internal state when sending the internal state out
return:
The created instance


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.


getVal

@SuppressWarnings("GroovyAssignabilityCheck")
public final T getVal()
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.


handleMessage

void handleMessage(Object message)
Dynamically dispatches the method call


onMessage

public final void onMessage(NullObject obj)
Accepts a NullObject instance and sets the internal state to null


onMessage

public final void onMessage(groovy.lang.Closure code)
Accepts and invokes the closure


onMessage

public final void onMessage(T message)
Other messages than closures are accepted as new values for the internal state


sendAndWait

public final def sendAndWait(groovy.lang.Closure message)
Submits the closure waiting for the result


updateValue

public final void updateValue(T newValue)
Allows closures to set the new internal state as a whole


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.
param:
callback A closure to invoke with the internal state as a parameter


 

Groovy Documentation