akka.agent
Class Agent<T>

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

public 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.

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.

Example of usage:

 val agent = Agent(5)

 agent send (_ * 2)

 ...

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

 agent.close
 

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

 agent1.close
 agent2.close
 agent3.close
 agent4.close
 

Constructor Summary

Agent(T initialValue, ActorRefFactory refFactory, ActorSystem system)

Agent(T initialValue, ActorSystem system)

Method Summary

scala.concurrent.Future<T>	alter(Function<T,T> f, scala.concurrent.duration.FiniteDuration timeout) Java API Dispatch a function to update the internal state, and return a Future where that new state can be obtained within the given timeout
scala.concurrent.Future<T>	alter(scala.Function1<T,T> f, Timeout timeout) Dispatch a function to update the internal state, and return a Future where that new state can be obtained within the given timeout.
void	alterOff(Function<T,T> f, scala.concurrent.duration.FiniteDuration timeout, scala.concurrent.ExecutionContext ec) Java API: Dispatch a function to update the internal state but on its own thread, and return a Future where that new state can be obtained within the given timeout.
scala.concurrent.Future<T>	alterOff(scala.Function1<T,T> f, Timeout timeout, 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 within the given timeout.
T	apply() Read the internal state of the agent.
T	await(Timeout timeout) Gets this agent's value after all currently queued updates have completed.
void	close() Closes the agents and makes it eligible for garbage collection.
<B> Agent<B>	flatMap(Function<T,Agent<B>> f) Java API: Flatmap this agent to a new agent, applying the function to the internal state.
<B> Agent<B>	flatMap(scala.Function1<T,Agent<B>> f) Flatmap this agent to a new agent, applying the function to the internal state.
<U> void	foreach(scala.Function1<T,U> f) Applies the function to the internal state.
void	foreach(Procedure<T> f) Java API: Applies the function to the internal state.
scala.concurrent.Future<T>	future(Timeout timeout) A future to the current value that will be completed after any currently queued updates.
T	get() Java API: Read the internal state of the agent.
<B> Agent<B>	map(Function<T,B> f) Java API: Map this agent to a new agent, applying the function to the internal state.
<B> Agent<B>	map(scala.Function1<T,B> f) Map this agent to a new agent, applying the function to the internal state.
void	resume() Resumes processing of send actions for the agent.
void	send(Function<T,T> f) Java API: Dispatch a function to update the internal state.
void	send(scala.Function1<T,T> f) Dispatch a function to update the internal state.
void	send(T newValue) Dispatch a new value for the internal state.
void	sendOff(Function<T,T> f, scala.concurrent.ExecutionContext ec) Java API: Dispatch a function to update the internal state but on its own thread.
void	sendOff(scala.Function1<T,T> f, scala.concurrent.ExecutionContext ec) Dispatch a function to update the internal state but on its own thread.
void	suspend() Suspends processing of send actions for the agent.
void	update(T newValue) Dispatch a new value for the internal state.

Methods inherited from class java.lang.Object

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

Constructor Detail

Agent

public Agent(T initialValue,
             ActorRefFactory refFactory,
             ActorSystem system)

Agent

public Agent(T initialValue,
             ActorSystem system)

Method Detail

get

public T get()

Java API: Read the internal state of the agent.

apply

public T apply()

Read the internal state of the agent.

send

public void send(scala.Function1<T,T> f)

Dispatch a function to update the internal state.

alter

public scala.concurrent.Future<T> alter(scala.Function1<T,T> f,
                                        Timeout timeout)

Dispatch a function to update the internal state, and return a Future where that new state can be obtained within the given timeout.

send

public void send(T newValue)

Dispatch a new value for the internal state. Behaves the same as sending a function (x => newValue).

update

public void update(T newValue)

Dispatch a new value for the internal state. Behaves the same as sending a function (x => newValue).

sendOff

public 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.

alterOff

public scala.concurrent.Future<T> alterOff(scala.Function1<T,T> f,
                                           Timeout timeout,
                                           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 within the given timeout. 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.

future

public scala.concurrent.Future<T> future(Timeout timeout)

A future to the current value that will be completed after any currently queued updates.

await

public T await(Timeout timeout)

Gets this agent's value after all currently queued updates have completed.

map

public <B> Agent<B> 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.

flatMap

public <B> Agent<B> flatMap(scala.Function1<T,Agent<B>> f)

Flatmap this agent to a new agent, applying the function to the internal state. Does not change the value of this agent.

foreach

public <U> void foreach(scala.Function1<T,U> f)

Applies the function to the internal state. Does not change the value of this agent.

suspend

public void suspend()

Suspends processing of send actions for the agent.

resume

public void resume()

Resumes processing of send actions for the agent.

close

public void close()

Closes the agents and makes it eligible for garbage collection. A closed agent cannot accept any send actions.

send

public void send(Function<T,T> f)

Java API: Dispatch a function to update the internal state.

alter

public scala.concurrent.Future<T> alter(Function<T,T> f,
                                        scala.concurrent.duration.FiniteDuration timeout)

Java API Dispatch a function to update the internal state, and return a Future where that new state can be obtained within the given timeout

sendOff

public void sendOff(Function<T,T> f,
                    scala.concurrent.ExecutionContext ec)

Java API: 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.

alterOff

public void alterOff(Function<T,T> f,
                     scala.concurrent.duration.FiniteDuration timeout,
                     scala.concurrent.ExecutionContext ec)

Java API: Dispatch a function to update the internal state but on its own thread, and return a Future where that new state can be obtained within the given timeout. 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.

map

public <B> Agent<B> map(Function<T,B> f)

Java API: Map this agent to a new agent, applying the function to the internal state. Does not change the value of this agent.

flatMap

public <B> Agent<B> flatMap(Function<T,Agent<B>> f)

Java API: Flatmap this agent to a new agent, applying the function to the internal state. Does not change the value of this agent.

foreach

public void foreach(Procedure<T> f)

Java API: Applies the function to the internal state. Does not change the value of this agent.