!str #19005 make groupBy et al return a SubFlow
A SubFlow (or SubSource) is not a Graph, it is an unfinished builder that accepts transformations. This allows us to capture the substreams’ transformations before materializing the flow, which will be very helpful in fully fusing all operators. Another change is that groupBy now requires a maxSubstreams parameter in order to bound its resource usage. In exchange the matching merge can be unbounded. This trades silent deadlock for explicit stream failure. This commit also changes all uses of Predef.identity to use `conforms` and removes the HTTP impl.util.identityFunc.
This commit is contained in:
Roland Kuhn
parent
654fa41443
commit
1500d1f36d
56 changed files with 3484 additions and 720 deletions
954
akka-stream/src/main/scala/akka/stream/javadsl/SubFlow.scala
Normal file
954
akka-stream/src/main/scala/akka/stream/javadsl/SubFlow.scala
Normal file
|
|
@ -0,0 +1,954 @@
|
|||
/**
|
||||
* Copyright (C) 2015 Typesafe Inc. <http://www.typesafe.com>
|
||||
*/
|
||||
package akka.stream.javadsl
|
||||
|
||||
import akka.event.LoggingAdapter
|
||||
import akka.japi.function
|
||||
import akka.stream._
|
||||
import akka.stream.impl.Stages.StageModule
|
||||
import akka.stream.impl.ConstantFun
|
||||
import akka.stream.stage.Stage
|
||||
import scala.collection.immutable
|
||||
import scala.collection.JavaConverters._
|
||||
import scala.annotation.unchecked.uncheckedVariance
|
||||
import scala.concurrent.Future
|
||||
import scala.concurrent.duration.FiniteDuration
|
||||
import akka.japi.Util
|
||||
|
||||
/**
|
||||
* A “stream of streams” sub-flow of data elements, e.g. produced by `groupBy`.
|
||||
* SubFlows cannot contribute to the super-flow’s materialized value since they
|
||||
* are materialized later, during the runtime of the flow graph processing.
|
||||
*/
|
||||
class SubFlow[-In, +Out, +Mat](delegate: scaladsl.SubFlow[Out, Mat, scaladsl.Flow[In, Out, Mat]#Repr, scaladsl.Sink[In, Mat]]) {
|
||||
|
||||
/** Converts this Flow to its Scala DSL counterpart */
|
||||
def asScala: scaladsl.SubFlow[Out, Mat, scaladsl.Flow[In, Out, Mat]#Repr, scaladsl.Sink[In, Mat]] @uncheckedVariance = delegate
|
||||
|
||||
/**
|
||||
* Flatten the sub-flows back into the super-flow by performing a merge.
|
||||
*/
|
||||
def mergeSubstreams(): Flow[In, Out, Mat] =
|
||||
new Flow(delegate.mergeSubstreams)
|
||||
|
||||
/**
|
||||
* Flatten the sub-flows back into the super-flow by concatenating them.
|
||||
* This is usually a bad idea when combined with `groupBy` since it can
|
||||
* easily lead to deadlock—the concatenation does not consume from the second
|
||||
* substream until the first has finished and the `groupBy` stage will get
|
||||
* back-pressure from the second stream.
|
||||
*/
|
||||
def concatSubstreams(): Flow[In, Out, Mat] =
|
||||
new Flow(delegate.concatSubstreams)
|
||||
|
||||
/**
|
||||
* Transform this [[Flow]] by appending the given processing steps.
|
||||
*
|
||||
* {{{
|
||||
* +----------------------------+
|
||||
* | Resulting Flow |
|
||||
* | |
|
||||
* | +------+ +------+ |
|
||||
* | | | | | |
|
||||
* In ~~> | this | ~Out~> | flow | ~~> T
|
||||
* | | | | | |
|
||||
* | +------+ +------+ |
|
||||
* +----------------------------+
|
||||
* }}}
|
||||
*
|
||||
* The materialized value of the combined [[Flow]] will be the materialized
|
||||
* value of the current flow (ignoring the other Flow’s value), use
|
||||
* [[Flow#viaMat viaMat]] if a different strategy is needed.
|
||||
*/
|
||||
def via[T, M](flow: Graph[FlowShape[Out, T], M]): SubFlow[In, T, Mat] =
|
||||
new SubFlow(delegate.via(flow))
|
||||
|
||||
/**
|
||||
* Connect this [[SubFlow]] to a [[Sink]], concatenating the processing steps of both.
|
||||
* This means that all sub-flows that result from the previous sub-stream operator
|
||||
* will be attached to the given sink.
|
||||
* {{{
|
||||
* +----------------------------+
|
||||
* | Resulting Sink |
|
||||
* | |
|
||||
* | +------+ +------+ |
|
||||
* | | | | | |
|
||||
* In ~~> | flow | ~Out~> | sink | |
|
||||
* | | | | | |
|
||||
* | +------+ +------+ |
|
||||
* +----------------------------+
|
||||
* }}}
|
||||
*/
|
||||
def to(sink: Graph[SinkShape[Out], _]): Sink[In, Mat] =
|
||||
new Sink(delegate.to(sink))
|
||||
|
||||
/**
|
||||
* Transform this stream by applying the given function to each of the elements
|
||||
* as they pass through this processing step.
|
||||
*
|
||||
* '''Emits when''' the mapping function returns an element
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def map[T](f: function.Function[Out, T]): SubFlow[In, T, Mat] =
|
||||
new SubFlow(delegate.map(f.apply))
|
||||
|
||||
/**
|
||||
* Transform each input element into an `Iterable` of output elements that is
|
||||
* then flattened into the output stream.
|
||||
*
|
||||
* Make sure that the `Iterable` is immutable or at least not modified after
|
||||
* being used as an output sequence. Otherwise the stream may fail with
|
||||
* `ConcurrentModificationException` or other more subtle errors may occur.
|
||||
*
|
||||
* The returned `Iterable` MUST NOT contain `null` values,
|
||||
* as they are illegal as stream elements - according to the Reactive Streams specification.
|
||||
*
|
||||
* '''Emits when''' the mapping function returns an element or there are still remaining elements
|
||||
* from the previously calculated collection
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures or there are still remaining elements from the
|
||||
* previously calculated collection
|
||||
*
|
||||
* '''Completes when''' upstream completes and all remaining elements has been emitted
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def mapConcat[T](f: function.Function[Out, java.lang.Iterable[T]]): SubFlow[In, T, Mat] =
|
||||
new SubFlow(delegate.mapConcat { elem ⇒ Util.immutableSeq(f(elem)) })
|
||||
|
||||
/**
|
||||
* Transform this stream by applying the given function to each of the elements
|
||||
* as they pass through this processing step. The function returns a `Future` and the
|
||||
* value of that future will be emitted downstreams. As many futures as requested elements by
|
||||
* downstream may run in parallel and may complete in any order, but the elements that
|
||||
* are emitted downstream are in the same order as received from upstream.
|
||||
*
|
||||
* If the function `f` throws an exception or if the `Future` is completed
|
||||
* with failure and the supervision decision is [[akka.stream.Supervision#stop]]
|
||||
* the stream will be completed with failure.
|
||||
*
|
||||
* If the function `f` throws an exception or if the `Future` is completed
|
||||
* with failure and the supervision decision is [[akka.stream.Supervision#resume]] or
|
||||
* [[akka.stream.Supervision#restart]] the element is dropped and the stream continues.
|
||||
*
|
||||
* The function `f` is always invoked on the elements in the order they arrive.
|
||||
*
|
||||
* '''Emits when''' the Future returned by the provided function finishes for the next element in sequence
|
||||
*
|
||||
* '''Backpressures when''' the number of futures reaches the configured parallelism and the downstream
|
||||
* backpressures or the first future is not completed
|
||||
*
|
||||
* '''Completes when''' upstream completes and all futures has been completed and all elements has been emitted
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*
|
||||
* @see [[#mapAsyncUnordered]]
|
||||
*/
|
||||
def mapAsync[T](parallelism: Int, f: function.Function[Out, Future[T]]): SubFlow[In, T, Mat] =
|
||||
new SubFlow(delegate.mapAsync(parallelism)(f.apply))
|
||||
|
||||
/**
|
||||
* Transform this stream by applying the given function to each of the elements
|
||||
* as they pass through this processing step. The function returns a `Future` and the
|
||||
* value of that future will be emitted downstreams. As many futures as requested elements by
|
||||
* downstream may run in parallel and each processed element will be emitted downstream
|
||||
* as soon as it is ready, i.e. it is possible that the elements are not emitted downstream
|
||||
* in the same order as received from upstream.
|
||||
*
|
||||
* If the function `f` throws an exception or if the `Future` is completed
|
||||
* with failure and the supervision decision is [[akka.stream.Supervision#stop]]
|
||||
* the stream will be completed with failure.
|
||||
*
|
||||
* If the function `f` throws an exception or if the `Future` is completed
|
||||
* with failure and the supervision decision is [[akka.stream.Supervision#resume]] or
|
||||
* [[akka.stream.Supervision#restart]] the element is dropped and the stream continues.
|
||||
*
|
||||
* The function `f` is always invoked on the elements in the order they arrive (even though the result of the futures
|
||||
* returned by `f` might be emitted in a different order).
|
||||
*
|
||||
* '''Emits when''' any of the Futures returned by the provided function complete
|
||||
*
|
||||
* '''Backpressures when''' the number of futures reaches the configured parallelism and the downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes and all futures has been completed and all elements has been emitted
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*
|
||||
* @see [[#mapAsync]]
|
||||
*/
|
||||
def mapAsyncUnordered[T](parallelism: Int, f: function.Function[Out, Future[T]]): SubFlow[In, T, Mat] =
|
||||
new SubFlow(delegate.mapAsyncUnordered(parallelism)(f.apply))
|
||||
|
||||
/**
|
||||
* Only pass on those elements that satisfy the given predicate.
|
||||
*
|
||||
* '''Emits when''' the given predicate returns true for the element
|
||||
*
|
||||
* '''Backpressures when''' the given predicate returns true for the element and downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*
|
||||
*/
|
||||
def filter(p: function.Predicate[Out]): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.filter(p.test))
|
||||
|
||||
/**
|
||||
* Only pass on those elements that NOT satisfy the given predicate.
|
||||
*
|
||||
* '''Emits when''' the given predicate returns false for the element
|
||||
*
|
||||
* '''Backpressures when''' the given predicate returns false for the element and downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def filterNot(p: function.Predicate[Out]): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.filterNot(p.test))
|
||||
|
||||
/**
|
||||
* Transform this stream by applying the given partial function to each of the elements
|
||||
* on which the function is defined as they pass through this processing step.
|
||||
* Non-matching elements are filtered out.
|
||||
*
|
||||
* '''Emits when''' the provided partial function is defined for the element
|
||||
*
|
||||
* '''Backpressures when''' the partial function is defined for the element and downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def collect[T](pf: PartialFunction[Out, T]): SubFlow[In, T, Mat] =
|
||||
new SubFlow(delegate.collect(pf))
|
||||
|
||||
/**
|
||||
* Chunk up this stream into groups of the given size, with the last group
|
||||
* possibly smaller than requested due to end-of-stream.
|
||||
*
|
||||
* `n` must be positive, otherwise IllegalArgumentException is thrown.
|
||||
*
|
||||
* '''Emits when''' the specified number of elements has been accumulated or upstream completed
|
||||
*
|
||||
* '''Backpressures when''' a group has been assembled and downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def grouped(n: Int): SubFlow[In, java.util.List[Out @uncheckedVariance], Mat] =
|
||||
new SubFlow(delegate.grouped(n).map(_.asJava)) // TODO optimize to one step
|
||||
|
||||
/**
|
||||
* Apply a sliding window over the stream and return the windows as groups of elements, with the last group
|
||||
* possibly smaller than requested due to end-of-stream.
|
||||
*
|
||||
* `n` must be positive, otherwise IllegalArgumentException is thrown.
|
||||
* `step` must be positive, otherwise IllegalArgumentException is thrown.
|
||||
*
|
||||
* '''Emits when''' enough elements have been collected within the window or upstream completed
|
||||
*
|
||||
* '''Backpressures when''' a window has been assembled and downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def sliding(n: Int, step: Int = 1): SubFlow[In, java.util.List[Out @uncheckedVariance], Mat] =
|
||||
new SubFlow(delegate.sliding(n, step).map(_.asJava)) // TODO optimize to one step
|
||||
|
||||
/**
|
||||
* Similar to `fold` but is not a terminal operation,
|
||||
* emits its current value which starts at `zero` and then
|
||||
* applies the current and next value to the given function `f`,
|
||||
* emitting the next current value.
|
||||
*
|
||||
* If the function `f` throws an exception and the supervision decision is
|
||||
* [[akka.stream.Supervision#restart]] current value starts at `zero` again
|
||||
* the stream will continue.
|
||||
*
|
||||
* '''Emits when''' the function scanning the element returns a new element
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def scan[T](zero: T)(f: function.Function2[T, Out, T]): SubFlow[In, T, Mat] =
|
||||
new SubFlow(delegate.scan(zero)(f.apply))
|
||||
|
||||
/**
|
||||
* Similar to `scan` but only emits its result when the upstream completes,
|
||||
* after which it also completes. Applies the given function `f` towards its current and next value,
|
||||
* yielding the next current value.
|
||||
*
|
||||
* If the function `f` throws an exception and the supervision decision is
|
||||
* [[akka.stream.Supervision#restart]] current value starts at `zero` again
|
||||
* the stream will continue.
|
||||
*
|
||||
* '''Emits when''' upstream completes
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def fold[T](zero: T)(f: function.Function2[T, Out, T]): SubFlow[In, T, Mat] =
|
||||
new SubFlow(delegate.fold(zero)(f.apply))
|
||||
|
||||
/**
|
||||
* Intersperses stream with provided element, similar to how [[scala.collection.immutable.List.mkString]]
|
||||
* injects a separator between a List's elements.
|
||||
*
|
||||
* Additionally can inject start and end marker elements to stream.
|
||||
*
|
||||
* Examples:
|
||||
*
|
||||
* {{{
|
||||
* Source<Integer, ?> nums = Source.from(Arrays.asList(0, 1, 2, 3));
|
||||
* nums.intersperse(","); // 1 , 2 , 3
|
||||
* nums.intersperse("[", ",", "]"); // [ 1 , 2 , 3 ]
|
||||
* }}}
|
||||
*
|
||||
* In case you want to only prepend or only append an element (yet still use the `intercept` feature
|
||||
* to inject a separator between elements, you may want to use the following pattern instead of the 3-argument
|
||||
* version of intersperse (See [[Source.concat]] for semantics details):
|
||||
*
|
||||
* {{{
|
||||
* Source.single(">> ").concat(flow.intersperse(","))
|
||||
* flow.intersperse(",").concat(Source.single("END"))
|
||||
* }}}
|
||||
*
|
||||
* '''Emits when''' upstream emits (or before with the `start` element if provided)
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def intersperse[T >: Out](start: T, inject: T, end: T): SubFlow[In, T, Mat] =
|
||||
new SubFlow(delegate.intersperse(start, inject, end))
|
||||
|
||||
/**
|
||||
* Intersperses stream with provided element, similar to how [[scala.collection.immutable.List.mkString]]
|
||||
* injects a separator between a List's elements.
|
||||
*
|
||||
* Additionally can inject start and end marker elements to stream.
|
||||
*
|
||||
* Examples:
|
||||
*
|
||||
* {{{
|
||||
* Source<Integer, ?> nums = Source.from(Arrays.asList(0, 1, 2, 3));
|
||||
* nums.intersperse(","); // 1 , 2 , 3
|
||||
* nums.intersperse("[", ",", "]"); // [ 1 , 2 , 3 ]
|
||||
* }}}
|
||||
*
|
||||
* '''Emits when''' upstream emits (or before with the `start` element if provided)
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def intersperse[T >: Out](inject: T): SubFlow[In, T, Mat] =
|
||||
new SubFlow(delegate.intersperse(inject))
|
||||
|
||||
/**
|
||||
* Chunk up this stream into groups of elements received within a time window,
|
||||
* or limited by the given number of elements, whatever happens first.
|
||||
* Empty groups will not be emitted if no elements are received from upstream.
|
||||
* The last group before end-of-stream will contain the buffered elements
|
||||
* since the previously emitted group.
|
||||
*
|
||||
* '''Emits when''' the configured time elapses since the last group has been emitted
|
||||
*
|
||||
* '''Backpressures when''' the configured time elapses since the last group has been emitted
|
||||
*
|
||||
* '''Completes when''' upstream completes (emits last group)
|
||||
*
|
||||
* '''Cancels when''' downstream completes
|
||||
*
|
||||
* `n` must be positive, and `d` must be greater than 0 seconds, otherwise
|
||||
* IllegalArgumentException is thrown.
|
||||
*/
|
||||
def groupedWithin(n: Int, d: FiniteDuration): SubFlow[In, java.util.List[Out @uncheckedVariance], Mat] =
|
||||
new SubFlow(delegate.groupedWithin(n, d).map(_.asJava)) // TODO optimize to one step
|
||||
|
||||
/**
|
||||
* Discard the given number of elements at the beginning of the stream.
|
||||
* No elements will be dropped if `n` is zero or negative.
|
||||
*
|
||||
* '''Emits when''' the specified number of elements has been dropped already
|
||||
*
|
||||
* '''Backpressures when''' the specified number of elements has been dropped and downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def drop(n: Long): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.drop(n))
|
||||
|
||||
/**
|
||||
* Discard the elements received within the given duration at beginning of the stream.
|
||||
*
|
||||
* '''Emits when''' the specified time elapsed and a new upstream element arrives
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def dropWithin(d: FiniteDuration): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.dropWithin(d))
|
||||
|
||||
/**
|
||||
* Terminate processing (and cancel the upstream publisher) after predicate
|
||||
* returns false for the first time. Due to input buffering some elements may have been
|
||||
* requested from upstream publishers that will then not be processed downstream
|
||||
* of this step.
|
||||
*
|
||||
* The stream will be completed without producing any elements if predicate is false for
|
||||
* the first stream element.
|
||||
*
|
||||
* '''Emits when''' the predicate is true
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' predicate returned false or upstream completes
|
||||
*
|
||||
* '''Cancels when''' predicate returned false or downstream cancels
|
||||
*/
|
||||
def takeWhile(p: function.Predicate[Out]): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.takeWhile(p.test))
|
||||
|
||||
/**
|
||||
* Discard elements at the beginning of the stream while predicate is true.
|
||||
* All elements will be taken after predicate returns false first time.
|
||||
*
|
||||
* '''Emits when''' predicate returned false and for all following stream elements
|
||||
*
|
||||
* '''Backpressures when''' predicate returned false and downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def dropWhile(p: function.Predicate[Out]): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.dropWhile(p.test))
|
||||
|
||||
/**
|
||||
* Recover allows to send last element on failure and gracefully complete the stream
|
||||
* Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements.
|
||||
* This stage can recover the failure signal, but not the skipped elements, which will be dropped.
|
||||
*
|
||||
* '''Emits when''' element is available from the upstream or upstream is failed and pf returns an element
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes or upstream failed with exception pf can handle
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*
|
||||
*/
|
||||
def recover[T >: Out](pf: PartialFunction[Throwable, T]): SubFlow[In, T, Mat] =
|
||||
new SubFlow(delegate.recover(pf))
|
||||
|
||||
/**
|
||||
* Terminate processing (and cancel the upstream publisher) after the given
|
||||
* number of elements. Due to input buffering some elements may have been
|
||||
* requested from upstream publishers that will then not be processed downstream
|
||||
* of this step.
|
||||
*
|
||||
* The stream will be completed without producing any elements if `n` is zero
|
||||
* or negative.
|
||||
*
|
||||
* '''Emits when''' the specified number of elements to take has not yet been reached
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' the defined number of elements has been taken or upstream completes
|
||||
*
|
||||
* '''Cancels when''' the defined number of elements has been taken or downstream cancels
|
||||
*/
|
||||
def take(n: Long): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.take(n))
|
||||
|
||||
/**
|
||||
* Terminate processing (and cancel the upstream publisher) after the given
|
||||
* duration. Due to input buffering some elements may have been
|
||||
* requested from upstream publishers that will then not be processed downstream
|
||||
* of this step.
|
||||
*
|
||||
* Note that this can be combined with [[#take]] to limit the number of elements
|
||||
* within the duration.
|
||||
*
|
||||
* '''Emits when''' an upstream element arrives
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes or timer fires
|
||||
*
|
||||
* '''Cancels when''' downstream cancels or timer fires
|
||||
*/
|
||||
def takeWithin(d: FiniteDuration): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.takeWithin(d))
|
||||
|
||||
/**
|
||||
* Allows a faster upstream to progress independently of a slower subscriber by conflating elements into a summary
|
||||
* until the subscriber is ready to accept them. For example a conflate step might average incoming numbers if the
|
||||
* upstream publisher is faster.
|
||||
*
|
||||
* This element only rolls up elements if the upstream is faster, but if the downstream is faster it will not
|
||||
* duplicate elements.
|
||||
*
|
||||
* '''Emits when''' downstream stops backpressuring and there is a conflated element available
|
||||
*
|
||||
* '''Backpressures when''' never
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*
|
||||
* @param seed Provides the first state for a conflated value using the first unconsumed element as a start
|
||||
* @param aggregate Takes the currently aggregated value and the current pending element to produce a new aggregate
|
||||
*
|
||||
*/
|
||||
def conflate[S](seed: function.Function[Out, S], aggregate: function.Function2[S, Out, S]): SubFlow[In, S, Mat] =
|
||||
new SubFlow(delegate.conflate(seed.apply)(aggregate.apply))
|
||||
|
||||
/**
|
||||
* Allows a faster downstream to progress independently of a slower publisher by extrapolating elements from an older
|
||||
* element until new element comes from the upstream. For example an expand step might repeat the last element for
|
||||
* the subscriber until it receives an update from upstream.
|
||||
*
|
||||
* This element will never "drop" upstream elements as all elements go through at least one extrapolation step.
|
||||
* This means that if the upstream is actually faster than the upstream it will be backpressured by the downstream
|
||||
* subscriber.
|
||||
*
|
||||
* Expand does not support [[akka.stream.Supervision#restart]] and [[akka.stream.Supervision#resume]].
|
||||
* Exceptions from the `seed` or `extrapolate` functions will complete the stream with failure.
|
||||
*
|
||||
* '''Emits when''' downstream stops backpressuring
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*
|
||||
* @param seed Provides the first state for extrapolation using the first unconsumed element
|
||||
* @param extrapolate Takes the current extrapolation state to produce an output element and the next extrapolation
|
||||
* state.
|
||||
*/
|
||||
def expand[S, U](seed: function.Function[Out, S], extrapolate: function.Function[S, akka.japi.Pair[U, S]]): SubFlow[In, U, Mat] =
|
||||
new SubFlow(delegate.expand(seed(_))(s ⇒ {
|
||||
val p = extrapolate(s)
|
||||
(p.first, p.second)
|
||||
}))
|
||||
|
||||
/**
|
||||
* Adds a fixed size buffer in the flow that allows to store elements from a faster upstream until it becomes full.
|
||||
* Depending on the defined [[akka.stream.OverflowStrategy]] it might drop elements or backpressure the upstream if
|
||||
* there is no space available
|
||||
*
|
||||
* '''Emits when''' downstream stops backpressuring and there is a pending element in the buffer
|
||||
*
|
||||
* '''Backpressures when''' depending on OverflowStrategy
|
||||
* * Backpressure - backpressures when buffer is full
|
||||
* * DropHead, DropTail, DropBuffer - never backpressures
|
||||
* * Fail - fails the stream if buffer gets full
|
||||
*
|
||||
* '''Completes when''' upstream completes and buffered elements has been drained
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*
|
||||
* @param size The size of the buffer in element count
|
||||
* @param overflowStrategy Strategy that is used when incoming elements cannot fit inside the buffer
|
||||
*/
|
||||
def buffer(size: Int, overflowStrategy: OverflowStrategy): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.buffer(size, overflowStrategy))
|
||||
|
||||
/**
|
||||
* Generic transformation of a stream with a custom processing [[akka.stream.stage.Stage]].
|
||||
* This operator makes it possible to extend the `Flow` API when there is no specialized
|
||||
* operator that performs the transformation.
|
||||
*/
|
||||
def transform[U](mkStage: function.Creator[Stage[Out, U]]): SubFlow[In, U, Mat] =
|
||||
new SubFlow(delegate.transform(() ⇒ mkStage.create()))
|
||||
|
||||
/**
|
||||
* Takes up to `n` elements from the stream (less than `n` only if the upstream completes before emitting `n` elements)
|
||||
* and returns a pair containing a strict sequence of the taken element
|
||||
* and a stream representing the remaining elements. If ''n'' is zero or negative, then this will return a pair
|
||||
* of an empty collection and a stream containing the whole upstream unchanged.
|
||||
*
|
||||
* In case of an upstream error, depending on the current state
|
||||
* - the master stream signals the error if less than `n` elements has been seen, and therefore the substream
|
||||
* has not yet been emitted
|
||||
* - the tail substream signals the error after the prefix and tail has been emitted by the main stream
|
||||
* (at that point the main stream has already completed)
|
||||
*
|
||||
* '''Emits when''' the configured number of prefix elements are available. Emits this prefix, and the rest
|
||||
* as a substream
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures or substream backpressures
|
||||
*
|
||||
* '''Completes when''' prefix elements has been consumed and substream has been consumed
|
||||
*
|
||||
* '''Cancels when''' downstream cancels or substream cancels
|
||||
*/
|
||||
def prefixAndTail(n: Int): SubFlow[In, akka.japi.Pair[java.util.List[Out @uncheckedVariance], javadsl.Source[Out @uncheckedVariance, Unit]], Mat] =
|
||||
new SubFlow(delegate.prefixAndTail(n).map { case (taken, tail) ⇒ akka.japi.Pair(taken.asJava, tail.asJava) })
|
||||
|
||||
/**
|
||||
* Transform each input element into a `Source` of output elements that is
|
||||
* then flattened into the output stream by concatenation,
|
||||
* fully consuming one Source after the other.
|
||||
*
|
||||
* '''Emits when''' a currently consumed substream has an element available
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes and all consumed substreams complete
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*
|
||||
*/
|
||||
def flatMapConcat[T, M](f: function.Function[Out, _ <: Graph[SourceShape[T], M]]): SubFlow[In, T, Mat] =
|
||||
new SubFlow(delegate.flatMapConcat(x ⇒ f(x)))
|
||||
|
||||
/**
|
||||
* Transform each input element into a `Source` of output elements that is
|
||||
* then flattened into the output stream by merging, where at most `breadth`
|
||||
* substreams are being consumed at any given time.
|
||||
*
|
||||
* '''Emits when''' a currently consumed substream has an element available
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes and all consumed substreams complete
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def flatMapMerge[T, M](breadth: Int, f: function.Function[Out, _ <: Graph[SourceShape[T], M]]): SubFlow[In, T, Mat] =
|
||||
new SubFlow(delegate.flatMapMerge(breadth, o ⇒ f(o)))
|
||||
|
||||
/**
|
||||
* Concatenate the given [[Source]] to this [[Flow]], meaning that once this
|
||||
* Flow’s input is exhausted and all result elements have been generated,
|
||||
* the Source’s elements will be produced.
|
||||
*
|
||||
* Note that the [[Source]] is materialized together with this Flow and just kept
|
||||
* from producing elements by asserting back-pressure until its time comes.
|
||||
*
|
||||
* If this [[Flow]] gets upstream error - no elements from the given [[Source]] will be pulled.
|
||||
*
|
||||
* '''Emits when''' element is available from current stream or from the given [[Source]] when current is completed
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' given [[Source]] completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def concat[T >: Out, M](that: Graph[SourceShape[T], M]): SubFlow[In, T, Mat] =
|
||||
new SubFlow(delegate.concat(that))
|
||||
|
||||
/**
|
||||
* Attaches the given [[Sink]] to this [[Flow]], meaning that elements that passes
|
||||
* through will also be sent to the [[Sink]].
|
||||
*
|
||||
* '''Emits when''' element is available and demand exists both from the Sink and the downstream.
|
||||
*
|
||||
* '''Backpressures when''' downstream or Sink backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def alsoTo(that: Graph[SinkShape[Out], _]): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.alsoTo(that))
|
||||
|
||||
/**
|
||||
* Merge the given [[Source]] to this [[Flow]], taking elements as they arrive from input streams,
|
||||
* picking randomly when several elements ready.
|
||||
*
|
||||
* '''Emits when''' one of the inputs has an element available
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' all upstreams complete
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def merge[T >: Out](that: Graph[SourceShape[T], _]): SubFlow[In, T, Mat] =
|
||||
new SubFlow(delegate.merge(that))
|
||||
|
||||
/**
|
||||
* Combine the elements of current [[Flow]] and the given [[Source]] into a stream of tuples.
|
||||
*
|
||||
* '''Emits when''' all of the inputs has an element available
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' any upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def zip[T](source: Graph[SourceShape[T], _]): SubFlow[In, Out @uncheckedVariance Pair T, Mat] =
|
||||
new SubFlow(delegate.zip(source))
|
||||
|
||||
/**
|
||||
* Put together the elements of current [[Flow]] and the given [[Source]]
|
||||
* into a stream of combined elements using a combiner function.
|
||||
*
|
||||
* '''Emits when''' all of the inputs has an element available
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' any upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def zipWith[Out2, Out3](that: Graph[SourceShape[Out2], _],
|
||||
combine: function.Function2[Out, Out2, Out3]): SubFlow[In, Out3, Mat] =
|
||||
new SubFlow(delegate.zipWith[Out2, Out3](that)(combinerToScala(combine)))
|
||||
|
||||
/**
|
||||
* If the first element has not passed through this stage before the provided timeout, the stream is failed
|
||||
* with a [[java.util.concurrent.TimeoutException]].
|
||||
*
|
||||
* '''Emits when''' upstream emits an element
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes or fails if timeout elapses before first element arrives
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def initialTimeout(timeout: FiniteDuration): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.initialTimeout(timeout))
|
||||
|
||||
/**
|
||||
* If the completion of the stream does not happen until the provided timeout, the stream is failed
|
||||
* with a [[java.util.concurrent.TimeoutException]].
|
||||
*
|
||||
* '''Emits when''' upstream emits an element
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes or fails if timeout elapses before upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def completionTimeout(timeout: FiniteDuration): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.completionTimeout(timeout))
|
||||
|
||||
/**
|
||||
* If the time between two processed elements exceed the provided timeout, the stream is failed
|
||||
* with a [[java.util.concurrent.TimeoutException]].
|
||||
*
|
||||
* '''Emits when''' upstream emits an element
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes or fails if timeout elapses between two emitted elements
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def idleTimeout(timeout: FiniteDuration): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.idleTimeout(timeout))
|
||||
|
||||
/**
|
||||
* Injects additional elements if the upstream does not emit for a configured amount of time. In other words, this
|
||||
* stage attempts to maintains a base rate of emitted elements towards the downstream.
|
||||
*
|
||||
* If the downstream backpressures then no element is injected until downstream demand arrives. Injected elements
|
||||
* do not accumulate during this period.
|
||||
*
|
||||
* Upstream elements are always preferred over injected elements.
|
||||
*
|
||||
* '''Emits when''' upstream emits an element or if the upstream was idle for the configured period
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def keepAlive[U >: Out](maxIdle: FiniteDuration, injectedElem: function.Creator[U]): SubFlow[In, U, Mat] =
|
||||
new SubFlow(delegate.keepAlive(maxIdle, () ⇒ injectedElem.create()))
|
||||
|
||||
/**
|
||||
* Sends elements downstream with speed limited to `elements/per`. In other words, this stage set the maximum rate
|
||||
* for emitting messages. This combinator works for streams where all elements have the same cost or length.
|
||||
*
|
||||
* Throttle implements the token bucket model. There is a bucket with a given token capacity (burst size or maximumBurst).
|
||||
* Tokens drops into the bucket at a given rate and can be `spared` for later use up to bucket capacity
|
||||
* to allow some burstyness. Whenever stream wants to send an element, it takes as many
|
||||
* tokens from the bucket as number of elements. If there isn't any, throttle waits until the
|
||||
* bucket accumulates enough tokens.
|
||||
*
|
||||
* Parameter `mode` manages behaviour when upstream is faster than throttle rate:
|
||||
* - [[akka.stream.ThrottleMode.Shaping]] makes pauses before emitting messages to meet throttle rate
|
||||
* - [[akka.stream.ThrottleMode.Enforcing]] fails with exception when upstream is faster than throttle rate
|
||||
*
|
||||
* '''Emits when''' upstream emits an element and configured time per each element elapsed
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def throttle(elements: Int, per: FiniteDuration, maximumBurst: Int,
|
||||
mode: ThrottleMode): javadsl.SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.throttle(elements, per, maximumBurst, mode))
|
||||
|
||||
/**
|
||||
* Sends elements downstream with speed limited to `cost/per`. Cost is
|
||||
* calculating for each element individually by calling `calculateCost` function.
|
||||
* This combinator works for streams when elements have different cost(length).
|
||||
* Streams of `ByteString` for example.
|
||||
*
|
||||
* Throttle implements the token bucket model. There is a bucket with a given token capacity (burst size or maximumBurst).
|
||||
* Tokens drops into the bucket at a given rate and can be `spared` for later use up to bucket capacity
|
||||
* to allow some burstyness. Whenever stream wants to send an element, it takes as many
|
||||
* tokens from the bucket as element cost. If there isn't any, throttle waits until the
|
||||
* bucket accumulates enough tokens. Elements that costs more than the allowed burst will be delayed proportionally
|
||||
* to their cost minus available tokens, meeting the target rate.
|
||||
*
|
||||
* Parameter `mode` manages behaviour when upstream is faster than throttle rate:
|
||||
* - [[akka.stream.ThrottleMode.Shaping]] makes pauses before emitting messages to meet throttle rate
|
||||
* - [[akka.stream.ThrottleMode.Enforcing]] fails with exception when upstream is faster than throttle rate. Enforcing
|
||||
* cannot emit elements that cost more than the maximumBurst
|
||||
*
|
||||
* '''Emits when''' upstream emits an element and configured time per each element elapsed
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def throttle(cost: Int, per: FiniteDuration, maximumBurst: Int,
|
||||
costCalculation: function.Function[Out, Integer], mode: ThrottleMode): javadsl.SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.throttle(cost, per, maximumBurst, costCalculation.apply, mode))
|
||||
|
||||
/**
|
||||
* Delays the initial element by the specified duration.
|
||||
*
|
||||
* '''Emits when''' upstream emits an element if the initial delay already elapsed
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures or initial delay not yet elapsed
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def initialDelay(delay: FiniteDuration): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.initialDelay(delay))
|
||||
|
||||
def withAttributes(attr: Attributes): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.withAttributes(attr))
|
||||
|
||||
def named(name: String): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.named(name))
|
||||
|
||||
/**
|
||||
* Logs elements flowing through the stream as well as completion and erroring.
|
||||
*
|
||||
* By default element and completion signals are logged on debug level, and errors are logged on Error level.
|
||||
* This can be adjusted according to your needs by providing a custom [[Attributes.LogLevels]] attribute on the given Flow:
|
||||
*
|
||||
* The `extract` function will be applied to each element before logging, so it is possible to log only those fields
|
||||
* of a complex object flowing through this element.
|
||||
*
|
||||
* Uses the given [[LoggingAdapter]] for logging.
|
||||
*
|
||||
* '''Emits when''' the mapping function returns an element
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def log(name: String, extract: function.Function[Out, Any], log: LoggingAdapter): SubFlow[In, Out, Mat] =
|
||||
new SubFlow(delegate.log(name, e ⇒ extract.apply(e))(log))
|
||||
|
||||
/**
|
||||
* Logs elements flowing through the stream as well as completion and erroring.
|
||||
*
|
||||
* By default element and completion signals are logged on debug level, and errors are logged on Error level.
|
||||
* This can be adjusted according to your needs by providing a custom [[Attributes.LogLevels]] attribute on the given Flow:
|
||||
*
|
||||
* The `extract` function will be applied to each element before logging, so it is possible to log only those fields
|
||||
* of a complex object flowing through this element.
|
||||
*
|
||||
* Uses an internally created [[LoggingAdapter]] which uses `akka.stream.Log` as it's source (use this class to configure slf4j loggers).
|
||||
*
|
||||
* '''Emits when''' the mapping function returns an element
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def log(name: String, extract: function.Function[Out, Any]): SubFlow[In, Out, Mat] =
|
||||
this.log(name, extract, null)
|
||||
|
||||
/**
|
||||
* Logs elements flowing through the stream as well as completion and erroring.
|
||||
*
|
||||
* By default element and completion signals are logged on debug level, and errors are logged on Error level.
|
||||
* This can be adjusted according to your needs by providing a custom [[Attributes.LogLevels]] attribute on the given Flow:
|
||||
*
|
||||
* Uses the given [[LoggingAdapter]] for logging.
|
||||
*
|
||||
* '''Emits when''' the mapping function returns an element
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def log(name: String, log: LoggingAdapter): SubFlow[In, Out, Mat] =
|
||||
this.log(name, ConstantFun.javaIdentityFunction[Out], log)
|
||||
|
||||
/**
|
||||
* Logs elements flowing through the stream as well as completion and erroring.
|
||||
*
|
||||
* By default element and completion signals are logged on debug level, and errors are logged on Error level.
|
||||
* This can be adjusted according to your needs by providing a custom [[Attributes.LogLevels]] attribute on the given Flow.
|
||||
*
|
||||
* Uses an internally created [[LoggingAdapter]] which uses `akka.stream.Log` as it's source (use this class to configure slf4j loggers).
|
||||
*
|
||||
* '''Emits when''' the mapping function returns an element
|
||||
*
|
||||
* '''Backpressures when''' downstream backpressures
|
||||
*
|
||||
* '''Completes when''' upstream completes
|
||||
*
|
||||
* '''Cancels when''' downstream cancels
|
||||
*/
|
||||
def log(name: String): SubFlow[In, Out, Mat] =
|
||||
this.log(name, ConstantFun.javaIdentityFunction[Out], null)
|
||||
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue