From 4d072f08e471f9043d18980ca3a31ae991c07a4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martynas=20Mickevi=C4=8Dius?= Date: Fri, 22 Jan 2016 13:05:04 +0200 Subject: [PATCH] #19553 deprecate stage infra --- akka-docs/rst/general/stream/stages-overview.rst | 4 ++-- .../java/stream/migration-guide-2.0-2.4-java.rst | 15 +++++++++++++++ .../stream/migration-guide-2.0-2.4-scala.rst | 15 +++++++++++++++ .../src/main/scala/akka/stream/stage/Stage.scala | 5 +++++ 4 files changed, 37 insertions(+), 2 deletions(-) diff --git a/akka-docs/rst/general/stream/stages-overview.rst b/akka-docs/rst/general/stream/stages-overview.rst index fc9a66b703..a918ea2acc 100644 --- a/akka-docs/rst/general/stream/stages-overview.rst +++ b/akka-docs/rst/general/stream/stages-overview.rst @@ -20,7 +20,7 @@ Custom components are not covered by this table since their semantics are define Simple processing stages ^^^^^^^^^^^^^^^^^^^^^^^^ -These stages are all expressible as a ``PushPullStage``. These stages can transform the rate of incoming elements +These stages are all expressible as a ``GraphStage``. These stages can transform the rate of incoming elements since there are stages that emit multiple elements for a single input (e.g. `mapConcat') or consume multiple elements before emitting one output (e.g. ``filter``). However, these rate transformations are data-driven, i.e. it is the incoming elements that define how the rate is affected. This is in contrast with :ref:`detached-stages-overview` @@ -122,7 +122,7 @@ a single output combining the elements from all of the inputs in different ways. Stage Emits when Backpressures when Completes when ===================== ========================================================================================================================= ============================================================================================================================== ===================================================================================== merge one of the inputs has an element available downstream backpressures all upstreams complete (*) -mergeSorted all of the inputs have an element available downstream backpressures all upstreams complete +mergeSorted all of the inputs have an element available downstream backpressures all upstreams complete mergePreferred one of the inputs has an element available, preferring a defined input if multiple have elements available downstream backpressures all upstreams complete (*) zip all of the inputs have an element available downstream backpressures any upstream completes zipWith all of the inputs have an element available downstream backpressures any upstream completes diff --git a/akka-docs/rst/java/stream/migration-guide-2.0-2.4-java.rst b/akka-docs/rst/java/stream/migration-guide-2.0-2.4-java.rst index 10ccbed2b0..bbd2218004 100644 --- a/akka-docs/rst/java/stream/migration-guide-2.0-2.4-java.rst +++ b/akka-docs/rst/java/stream/migration-guide-2.0-2.4-java.rst @@ -98,3 +98,18 @@ Materialized values of the following sources and sinks: have been changed from ``Long`` to ``akka.stream.io.IOResult``. This allows to signal more complicated completion scenarios. For example, on failure it is now possible to return the exception and the number of bytes written until that exception occured. + +PushStage, PushPullStage and DetachedStage have been deprecated in favor of GraphStage +====================================================================================== + +The :class:`PushStage` :class:`PushPullStage` and :class:`DetachedStage` classes have been deprecated and +should be replaced by :class:`GraphStage` (:ref:`graphstage-java`) which is now a single powerful API +for custom stream processing. + +Update procedure +---------------- + +Please consult the :class:`GraphStage` documentation (:ref:`graphstage-java`) and the `previous migration guide`_ +on migrating from :class:`AsyncStage` to :class:`GraphStage`. + +.. _`previous migration guide`: http://doc.akka.io/docs/akka-stream-and-http-experimental/2.0.2/java/migration-guide-1.0-2.x-java.html#AsyncStage_has_been_replaced_by_GraphStage diff --git a/akka-docs/rst/scala/stream/migration-guide-2.0-2.4-scala.rst b/akka-docs/rst/scala/stream/migration-guide-2.0-2.4-scala.rst index 9d7f4d5bd7..0ad2dcc68c 100644 --- a/akka-docs/rst/scala/stream/migration-guide-2.0-2.4-scala.rst +++ b/akka-docs/rst/scala/stream/migration-guide-2.0-2.4-scala.rst @@ -87,3 +87,18 @@ Materialized values of the following sources and sinks: have been changed from ``Long`` to ``akka.stream.io.IOResult``. This allows to signal more complicated completion scenarios. For example, on failure it is now possible to return the exception and the number of bytes written until that exception occured. + +PushStage, PushPullStage and DetachedStage have been deprecated in favor of GraphStage +====================================================================================== + +The :class:`PushStage` :class:`PushPullStage` and :class:`DetachedStage` classes have been deprecated and +should be replaced by :class:`GraphStage` (:ref:`graphstage-scala`) which is now a single powerful API +for custom stream processing. + +Update procedure +---------------- + +Please consult the :class:`GraphStage` documentation (:ref:`graphstage-scala`) and the `previous migration guide`_ +on migrating from :class:`AsyncStage` to :class:`GraphStage`. + +.. _`previous migration guide`: http://doc.akka.io/docs/akka-stream-and-http-experimental/2.0.2/scala/migration-guide-1.0-2.x-scala.html#AsyncStage_has_been_replaced_by_GraphStage diff --git a/akka-stream/src/main/scala/akka/stream/stage/Stage.scala b/akka-stream/src/main/scala/akka/stream/stage/Stage.scala index 14ef6064c4..621fe07e45 100644 --- a/akka-stream/src/main/scala/akka/stream/stage/Stage.scala +++ b/akka-stream/src/main/scala/akka/stream/stage/Stage.scala @@ -29,6 +29,7 @@ import scala.util.control.NonFatal * @see [[akka.stream.scaladsl.Flow#transform]] * @see [[akka.stream.javadsl.Flow#transform]] */ +@deprecated("Please use GraphStage instead.", "2.4.2") sealed trait Stage[-In, +Out] /** @@ -185,6 +186,7 @@ private[stream] object AbstractStage { extends PushPullGraphStageWithMaterializedValue[In, Out, Ext, NotUsed]((att: Attributes) ⇒ (_factory(att), NotUsed), _stageAttributes) } +@deprecated("Please use GraphStage instead.", "2.4.2") abstract class AbstractStage[-In, Out, PushD <: Directive, PullD <: Directive, Ctx <: Context[Out], LifeCtx <: LifecycleContext] extends Stage[In, Out] { /** @@ -331,11 +333,13 @@ abstract class AbstractStage[-In, Out, PushD <: Directive, PullD <: Directive, C * @see [[StatefulStage]] * @see [[PushStage]] */ +@deprecated("Please use GraphStage instead.", "2.4.2") abstract class PushPullStage[In, Out] extends AbstractStage[In, Out, SyncDirective, SyncDirective, Context[Out], LifecycleContext] /** * `PushStage` is a [[PushPullStage]] that always perform transitive pull by calling `ctx.pull` from `onPull`. */ +@deprecated("Please use GraphStage instead.", "2.4.2") abstract class PushStage[In, Out] extends PushPullStage[In, Out] { /** * Always pulls from upstream. @@ -365,6 +369,7 @@ abstract class PushStage[In, Out] extends PushPullStage[In, Out] { * * @see [[PushPullStage]] */ +@deprecated("Please use GraphStage instead.", "2.4.2") abstract class DetachedStage[In, Out] extends AbstractStage[In, Out, UpstreamDirective, DownstreamDirective, DetachedContext[Out], LifecycleContext] { private[stream] override def isDetached = true