groovyx.gpars.agent
Class Agent<T>

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

public class Agent<T>
extends AgentBase<T>

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

Field Summary
 
Fields inherited from class groovyx.gpars.agent.AgentBase
data, lock
 
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
<T> Agent<T>
agent(T state)
          Creates an agent instance initialized with the given state.
static
<T> Agent<T>
agent(T state, groovy.lang.Closure copy)
          Creates an agent instance initialized with the given state.
static
<T> Agent<T>
fairAgent(T 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
<T> Agent<T>
fairAgent(T state, groovy.lang.Closure copy)
          Creates an agent instance initialized with the given state, which will cooperate in thread sharing with other agents and actors in a fair manner.
 void handleMessage(java.lang.Object message)
          Dynamically dispatches the method call
 
Methods inherited from class groovyx.gpars.agent.AgentBase
addListener, addValidator, await, getInstantVal, getVal, onMessage, onMessage, onMessage, sendAndWait, updateValue, valAsync
 
Methods inherited from class groovyx.gpars.agent.AgentCore
attachToThreadPool, call, getErrors, 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
 

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

Parameters:
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

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

handleMessage

public void handleMessage(java.lang.Object message)
Dynamically dispatches the method call

Specified by:
handleMessage in class AgentCore
Parameters:
message - A value or a closure

agent

public static <T> Agent<T> agent(T state)
Creates an agent instance initialized with the given state. The instance will use the default thread pool.

Parameters:
state - The initial internal state of the new Agent instance
Returns:
The created instance

agent

public static <T> Agent<T> agent(T state,
                                 groovy.lang.Closure copy)
Creates an agent instance initialized with the given state. The instance will use the default thread pool.

Parameters:
state - The initial internal state of the new Agent instance
copy - A closure to use to create a copy of the internal state when sending the internal state out
Returns:
The created instance

fairAgent

public static <T> Agent<T> fairAgent(T 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.

Parameters:
state - The initial internal state of the new Agent instance
Returns:
The created instance

fairAgent

public static <T> Agent<T> fairAgent(T state,
                                     groovy.lang.Closure copy)
Creates an agent instance initialized with the given state, which will cooperate in thread sharing with other agents and actors in a fair manner. The instance will use the default thread pool.

Parameters:
state - The initial internal state of the new Agent instance
copy - A closure to use to create a copy of the internal state when sending the internal state out
Returns:
The created instance

Copyright © 2008–2012 Václav Pech. All Rights Reserved.