diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/throttle.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/throttle.md index f4b8e4aafc..cd0a48d78b 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/throttle.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/throttle.md @@ -14,18 +14,15 @@ Limit the throughput to a specific number of elements per time unit, or a specif Limit the throughput to a specific number of elements per time unit, or a specific total cost per time unit, where a function has to be provided to calculate the individual cost of each element. -The throttle operator combines will with the @ref[`queue`](./../Source/queue.md) operator to adapt the speeds on both ends of the `queue`-`throttle` pair. - +The throttle operator combines well with the @ref[`queue`](./../Source/queue.md) operator to adapt the speeds on both ends of the `queue`-`throttle` pair. See also @ref:[Buffers and working with rate](../../stream-rate.md) for related operators. ## Example -Imagine the server end of a streaming platform. When a client connects and requesta a video content, the server -should return the content. Instead of serving a complete video as soon as bandwith allows, `throttle` can be used -to burst the first 30 seconds and then send a constant of 24 frames per second (let's imagine this streaming -platform stores frames, not bytes). This allows the browser to buffer 30 seconds in case there's a network -outage but prevents sending too much video content at once using all bandwitdh of the user's bandwitdh. +Imagine the server end of a streaming platform. When a client connects and request a video content, the server +should return the content. Instead of serving a complete video as fast as bandwith allows, `throttle` can be used +to limit the network usage to 24 frames per second (let's imagine this streaming platform stores frames, not bytes). Scala : @@snip [Throttle.scala](/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/Throttle.scala) { #throttle } @@ -33,6 +30,25 @@ Scala Java : @@snip [Throttle.java](/akka-docs/src/test/java/jdocs/stream/operators/sourceorflow/Throttle.java) { #throttle } +The problem in the example above is that when there's a network hiccup, the video playback will interrupt. It can be +improved by sending more content than the necessary ahead of time and let the client buffer that. So, `throttle` can be used +to burst the first 30 seconds and then send a constant of 24 frames per second. This way, when a request comes in +a good chunk of content will be downloaded and after that the server will activate the throttling. + +Scala +: @@snip [Throttle.scala](/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/Throttle.scala) { #throttle-with-burst } + +Java +: @@snip [Throttle.java](/akka-docs/src/test/java/jdocs/stream/operators/sourceorflow/Throttle.java) { #throttle-with-burst } + +The extra argument to set the `ThrottleMode` to `shapping` tells `throttle` to make pauses to avoid exceeding +the maximum rate. Alternatively we could set the throttling mode to cause a stream failure when upstream is faster +than the throttle rate. + +The examples above don't cover all the parameters supported by `throttle` (e.g `cost`-based throttling). See the +@apidoc[api documentation](Flow) { scala="#throttle(cost:Int,per:scala.concurrent.duration.FiniteDuration,maximumBurst:Int,costCalculation:Out=>Int,mode:akka.stream.ThrottleMode):FlowOps.this.Repr[Out]" java="#throttle(int,java.time.Duration,int,akka.japi.function.Function,akka.stream.ThrottleMode)" } +for all the details. + ## Reactive Streams semantics @@@div { .callout } diff --git a/akka-docs/src/test/java/jdocs/stream/operators/sourceorflow/Throttle.java b/akka-docs/src/test/java/jdocs/stream/operators/sourceorflow/Throttle.java index 75d2b4c164..d80f337491 100644 --- a/akka-docs/src/test/java/jdocs/stream/operators/sourceorflow/Throttle.java +++ b/akka-docs/src/test/java/jdocs/stream/operators/sourceorflow/Throttle.java @@ -31,10 +31,18 @@ public class Throttle { Source videoThrottling = frameSource.throttle( - framesPerSecond, Duration.ofSeconds(1), framesPerSecond * 30, ThrottleMode.shaping()); + framesPerSecond, Duration.ofSeconds(1)); // serialize `Frame` and send over the network. // #throttle + // #throttle-with-burst + Source throttlingWithBurst = + frameSource.throttle( + framesPerSecond, Duration.ofSeconds(1), framesPerSecond * 30, ThrottleMode.shaping()); + // serialize `Frame` and send over the network. + // #throttle-with-burst + videoThrottling.map(f -> f.i()).to(Sink.foreach(System.out::println)).run(mat); + throttlingWithBurst.take(1000L).map(f -> f.i()).to(Sink.foreach(System.out::println)).run(mat); } } diff --git a/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/Throttle.scala b/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/Throttle.scala index 301341b9c3..d07d9d992a 100644 --- a/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/Throttle.scala +++ b/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/Throttle.scala @@ -28,13 +28,22 @@ object Throttle extends App { // val frameSource: Source[Frame,_] val videoThrottling = frameSource.throttle( framesPerSecond, - 1.second, - framesPerSecond * 30, // maximumBurst - ThrottleMode.shaping) + 1.second) // serialize `Frame` and send over the network. // #throttle - videoThrottling.to(Sink.foreach(println)).run() + // #throttle-with-burst + // val frameSource: Source[Frame,_] + val videoThrottlingWithBurst = frameSource.throttle( + framesPerSecond, + 1.second, + framesPerSecond * 30, // maximumBurst + ThrottleMode.Shaping) + // serialize `Frame` and send over the network. + // #throttle-with-burst + + videoThrottling.take(1000).to(Sink.foreach(println)).run() + videoThrottlingWithBurst.take(1000).to(Sink.foreach(println)).run() } object ThrottleCommon {