From d1d4985950d96e0e914803dbd875087a36bed8cb Mon Sep 17 00:00:00 2001 From: Konrad Malawski Date: Wed, 30 Nov 2016 15:00:09 +0100 Subject: [PATCH] !agnt #21423 agents to be deprecated (#21913) --- akka-agent/src/main/scala/akka/agent/Agent.scala | 10 +++++++++- akka-docs/rst/java/agents.rst | 11 ++++++++--- .../rst/project/migration-guide-2.4.x-2.5.x.rst | 15 +++++++++++++++ akka-docs/rst/scala/agents.rst | 11 ++++++++--- 4 files changed, 40 insertions(+), 7 deletions(-) diff --git a/akka-agent/src/main/scala/akka/agent/Agent.scala b/akka-agent/src/main/scala/akka/agent/Agent.scala index 129ec8faa2..3ed6da63f3 100644 --- a/akka-agent/src/main/scala/akka/agent/Agent.scala +++ b/akka-agent/src/main/scala/akka/agent/Agent.scala @@ -6,17 +6,22 @@ package akka.agent import scala.concurrent.stm._ import scala.concurrent.{ ExecutionContext, Future, Promise } -import akka.util.{ SerializedSuspendableExecutionContext } +import akka.util.SerializedSuspendableExecutionContext +@deprecated("Agents are deprecated and scheduled for removal in the next major version, use Actors instead.", since = "2.5.0") object Agent { /** * Factory method for creating an Agent. */ + @deprecated("Agents are deprecated and scheduled for removal in the next major version, use Actors instead.", since = "2.5.0") def apply[T](initialValue: T)(implicit context: ExecutionContext): Agent[T] = new SecretAgent(initialValue, context) /** * Java API: Factory method for creating an Agent. + * @deprecated Agents are deprecated and scheduled for removal in the next major version, use Actors instead.i */ + @Deprecated + @deprecated("Agents are deprecated and scheduled for removal in the next major version, use Actors instead.", since = "2.5.0") def create[T](initialValue: T, context: ExecutionContext): Agent[T] = Agent(initialValue)(context) /** @@ -151,7 +156,10 @@ object Agent { * 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. + * + * @deprecated Agents are deprecated and scheduled for removal in the next major version, use Actors instead. */ +@deprecated("Agents are deprecated and scheduled for removal in the next major version, use Actors instead.", since = "2.5.0") abstract class Agent[T] { /** diff --git a/akka-docs/rst/java/agents.rst b/akka-docs/rst/java/agents.rst index 34d2e0e7d1..80d7a44c95 100644 --- a/akka-docs/rst/java/agents.rst +++ b/akka-docs/rst/java/agents.rst @@ -1,11 +1,16 @@ .. _agents-java: -######## - Agents -######## +Agents +###### Agents in Akka are inspired by `agents in Clojure`_. +.. warning:: + **Deprecation warning** - Agents have been deprecated and are scheduled for removal + in the next major version. We have found that their leaky abstraction (they do not + work over the network) make them inferior to pure Actors, and in face of the soon + inclusion of Akka Typed we see little value in maintaining the current Agents. + .. _agents in Clojure: http://clojure.org/agents Agents provide asynchronous change of individual locations. Agents are bound to diff --git a/akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst b/akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst index 663dae3cbf..774271a207 100644 --- a/akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst +++ b/akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst @@ -4,6 +4,21 @@ Upcoming Migration Guide 2.4.x to 2.5.x ####################################### +Agents +====== + +Agents are now deprecated +------------------------- + +Akka Agents are a very simple way of containing mutable state and allowing to access it safely from +multiple threads. The abstraction is leaky though, as Agents do not work over the network (unlike Akka Actors). + +As users were often confused by "when to use an Actor vs. when to use an Agent?" a decision was made to deprecate +the Agents, as they rarely are really enough and do not fit the Akka spirit of thinking about distribution. +We also anticipate to replace the uses of Agents by the upcoming Akka Typed, so in preparation thereof the Agents have been deprecated in 2.5. + +If you use Agents and would like to take over the maintanance thereof, please contact the team on gitter or github. + Akka Persistence ================ diff --git a/akka-docs/rst/scala/agents.rst b/akka-docs/rst/scala/agents.rst index 0a9bff45be..472494057a 100644 --- a/akka-docs/rst/scala/agents.rst +++ b/akka-docs/rst/scala/agents.rst @@ -1,11 +1,16 @@ .. _agents-scala: -######## - Agents -######## +Agents +###### Agents in Akka are inspired by `agents in Clojure`_. +.. warning:: + **Deprecation warning** - Agents have been deprecated and are scheduled for removal + in the next major version. We have found that their leaky abstraction (they do not + work over the network) make them inferior to pure Actors, and in face of the soon + inclusion of Akka Typed we see little value in maintaining the current Agents. + .. _agents in Clojure: http://clojure.org/agents Agents provide asynchronous change of individual locations. Agents are bound to