Agent

java.lang.Object
- akka.agent.Agent<T>

```
public abstract class Agent<T>
extends java.lang.Object
```
The Agent class was inspired by agents in Clojure.
Agents provide asynchronous change of individual locations. Agents are bound to a single storage location for their lifetime, and only allow mutation of that location (to a new state) to occur as a result of an action. Update actions are functions that are asynchronously applied to the Agent's state and whose return value becomes the Agent's new state. The state of an Agent should be immutable.
While updates to Agents are asynchronous, the state of an Agent is always immediately available for reading by any thread (using ''get'' or ''apply'') without any messages.
Agents are reactive. The update actions of all Agents get interleaved amongst threads in a thread pool. At any point in time, at most one ''send'' action for each Agent is being executed. Actions dispatched to an agent from another thread will occur in the order they were sent, potentially interleaved with actions dispatched to the same agent from other sources.
Example of usage:
```
 val agent = Agent(5)

 agent send (_ * 2)

 ...

 val result = agent()
 // use result ...

 
```
Agent is also monadic, which means that you can compose operations using for-comprehensions. In monadic usage the original agents are not touched but new agents are created. So the old values (agents) are still available as-is. They are so-called 'persistent'.
Example of monadic usage:
```
 val agent1 = Agent(3)
 val agent2 = Agent(5)

 for (value <- agent1) {
 result = value + 1
 }

 val agent3 = for (value <- agent1) yield value + 1

 val agent4 = for {
 value1 <- agent1
 value2 <- agent2
 } yield value1 + value2

 
```
==DEPRECATED STM SUPPORT==
Agents participating in enclosing STM transaction is a deprecated feature in 2.3.
If an Agent is used within an enclosing transaction, then it will participate in that transaction. Agents are integrated with the STM - any dispatches made in a transaction are held until that transaction commits, and are discarded if it is retried or aborted.

Constructor Summary

Constructors
Constructor and Description

Agent()

Constructors
Constructor and Description
`Agent()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`abstract scala.concurrent.Future<T>`	`alter(scala.Function1<T,T> f)` Dispatch a function to update the internal state, and return a Future where that new state can be obtained.
`abstract scala.concurrent.Future<T>`	`alter(T newValue)` Dispatch an update to the internal state, and return a Future where that new state can be obtained.
`abstract scala.concurrent.Future<T>`	`alterOff(scala.Function1<T,T> f, scala.concurrent.ExecutionContext ec)` Dispatch a function to update the internal state but on its own thread, and return a Future where that new state can be obtained.
`T`	`apply()` Read the internal state of the agent.
`static <T> Agent<T>`	`create(T initialValue, scala.concurrent.ExecutionContext context)` Java API: Factory method for creating an Agent.
`abstract <B> Agent<B>`	`flatMap(scala.Function1<T,Agent<B>> f)` Flatmap this agent to a new agent, applying the function to the internal state.
`abstract <U> void`	`foreach(scala.Function1<T,U> f)` Applies the function to the internal state.
`abstract scala.concurrent.Future<T>`	`future()` A future to the current value that will be completed after any currently queued updates.
`abstract T`	`get()` Java API: Read the internal state of the agent.
`abstract <B> Agent<B>`	`map(scala.Function1<T,B> f)` Map this agent to a new agent, applying the function to the internal state.
`abstract void`	`send(scala.Function1<T,T> f)` Dispatch a function to update the internal state.
`abstract void`	`send(T newValue)` Dispatch a new value for the internal state.
`abstract void`	`sendOff(scala.Function1<T,T> f, scala.concurrent.ExecutionContext ec)` Dispatch a function to update the internal state but on its own thread.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
 - Agent
```
public Agent()
```
- Method Detail
 - create
```
public static <T> Agent<T> create(T initialValue,
 scala.concurrent.ExecutionContext context)
```
 Java API: Factory method for creating an Agent.
 
 Parameters:
 
 initialValue - (undocumented)
 
 context - (undocumented)
 
 Returns:
 
 (undocumented)
 - get
```
public abstract T get()
```
 Java API: Read the internal state of the agent.
 
 Returns:
 
 (undocumented)
 - apply
```
public T apply()
```
 Read the internal state of the agent.
 
 Returns:
 
 (undocumented)
 - send
```
public abstract void send(T newValue)
```
 Dispatch a new value for the internal state. Behaves the same as sending a function (x => newValue).
 
 Parameters:
 
 newValue - (undocumented)
 - send
```
public abstract void send(scala.Function1<T,T> f)
```
 Dispatch a function to update the internal state. In Java, pass in an instance of akka.dispatch.Mapper.
 
 Parameters:
 
 f - (undocumented)
 - sendOff
```
public abstract void sendOff(scala.Function1<T,T> f,
 scala.concurrent.ExecutionContext ec)
```
 Dispatch a function to update the internal state but on its own thread. This does not use the reactive thread pool and can be used for long-running or blocking operations. Dispatches using either sendOff or send will still be executed in order. In Java, pass in an instance of akka.dispatch.Mapper.
 
 Parameters:
 
 f - (undocumented)
 
 ec - (undocumented)
 - alter
```
public abstract scala.concurrent.Future<T> alter(T newValue)
```
 Dispatch an update to the internal state, and return a Future where that new state can be obtained. In Java, pass in an instance of akka.dispatch.Mapper.
 
 Parameters:
 
 newValue - (undocumented)
 
 Returns:
 
 (undocumented)
 - alter
```
public abstract scala.concurrent.Future<T> alter(scala.Function1<T,T> f)
```
 Dispatch a function to update the internal state, and return a Future where that new state can be obtained. In Java, pass in an instance of akka.dispatch.Mapper.
 
 Parameters:
 
 f - (undocumented)
 
 Returns:
 
 (undocumented)
 - alterOff
```
public abstract scala.concurrent.Future<T> alterOff(scala.Function1<T,T> f,
 scala.concurrent.ExecutionContext ec)
```
 Dispatch a function to update the internal state but on its own thread, and return a Future where that new state can be obtained. This does not use the reactive thread pool and can be used for long-running or blocking operations. Dispatches using either alterOff or alter will still be executed in order. In Java, pass in an instance of akka.dispatch.Mapper.
 
 Parameters:
 
 f - (undocumented)
 
 ec - (undocumented)
 
 Returns:
 
 (undocumented)
 - future
```
public abstract scala.concurrent.Future<T> future()
```
 A future to the current value that will be completed after any currently queued updates.
 
 Returns:
 
 (undocumented)
 - map
```
public abstract  Agent map(scala.Function1<T,B> f)
```
 Map this agent to a new agent, applying the function to the internal state. Does not change the value of this agent. In Java, pass in an instance of akka.dispatch.Mapper.
 
 Parameters:
 
 f - (undocumented)
 
 Returns:
 
 (undocumented)
 - flatMap
```
public abstract  Agent flatMap(scala.Function1<T,Agent> f)
```
 Flatmap this agent to a new agent, applying the function to the internal state. Does not change the value of this agent. In Java, pass in an instance of akka.dispatch.Mapper.
 
 Parameters:
 
 f - (undocumented)
 
 Returns:
 
 (undocumented)
 - foreach
```
public abstract  void foreach(scala.Function1<T,U> f)
```
 Applies the function to the internal state. Does not change the value of this agent. In Java, pass in an instance of akka.dispatch.Foreach.
 
 Parameters:
 
 f - (undocumented)

Class Agent<T>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Agent

Method Detail

create

get

apply

send

send

sendOff

alter

alter

alterOff

future

map

flatMap

foreach