raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 10

some doc changes (#1177)

Browse source
This commit is contained in:
PJ Fanning 2024-03-09 13:57:01 +01:00 • committed by GitHub
parent fa5c83f36f
commit 06cff559a4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
13 changed files with 32 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

2
actor-testkit-typed/src/main/scala/org/apache/pekko/actor/testkit/typed/internal/ActorSystemStub.scala
View file

@ -137,7 +137,7 @@ import pekko.util.FutureConverters._
@InternalApi private[pekko] object ActorSystemStub {
object config {
// this is backward compatible with the old behaviour, hence it uses the loader used to load the test-kit
// this is backward compatible with the old behavior, hence it uses the loader used to load the test-kit
// which is not necessarily the one used to load the tests...
// hence this might not include reference config related to the actually executing test
// todo: might be better NOT to pass any class loader and let typesafeConfig rely on the contextClassLoader

12
docs/src/main/paradox/project/migration-guide-1.0.x-1.1.x.md
View file

@ -14,11 +14,11 @@ You may have to add explicit dependencies to the new Apache Pekko version in you
That said, there are some changes to configuration and behavior that should be considered, so
reading this migration guide and testing your application thoroughly is recommended.
## `Source.splitWhen`/`Flow.splitWhen`/`Source.splitAfter`/`Flow.splitAfter` behavioural change
## splitWhen/splitAfter behavior change
In Apache Pekko 1.0.x, the `splitWhen`/`splitAfter` stream operators on `Source`/`Flow` had an optional
`SubstreamCancelStrategy` parameter which defaulted to `SubstreamCancelStrategy.drain`. In Apache Pekko
1.1.x the usage of `SubstreamCancelStrategy` has been deprecated and instead `splitWhen`/`splitAfter`
1.1.x, the usage of `SubstreamCancelStrategy` has been deprecated and instead `splitWhen`/`splitAfter`
inherits the already existing `Supervision` strategy `Attribute` to achieve the same effect with the
following translation
@ -27,14 +27,14 @@ following translation
* `Supervision.restart` doesn't have an equivalent `SubstreamCancelStrategy`. Since it doesn't make semantic
sense for `SubFlow`s it behaves the same way as `Supervision.stop`.
The potential behavioural change results from the fact that in Apache Pekko Streams the default `Supervision`
The potential behavior change results from the fact that in Apache Pekko Streams the default `Supervision`
strategy is `Supervision.stop` whereas the default `SubstreamCancelStrategy` for Apache Pekko 1.0.x is
`SubstreamCancelStrategy.drain` (which translates to `Supervision.resume` in Apache Pekko 1.1.x). This means
that when you upgrade from Apache Pekko 1.0.x to 1.1.x its possible that previously if `SubFlow`s
resulted in errors the parent stream would continue to operate whereas in Apache Pekko 1.1.x the stream would cancel.
If you would like to keep the previous Apache Pekko 1.0.x behaviour you can just specify the
`Supervision.resumingDecider` attribute on your stream in the standard way, i.e. you would change
If you would like to keep the previous Apache Pekko 1.0.x behavior you can just specify the
`Supervision.resumingDecider` attribute on your stream in the standard way. That is, you would change
@@@div { .group-java }
```java
@ -67,6 +67,6 @@ source
@@@
If you already happen to have already explicitly defined a `SubstreamCancelStrategy` in the
`splitWhen`/`splitAfter` operators then there won't be any behavioural change albeit you
`splitWhen`/`splitAfter` operators then there won't be any behavior change albeit you
will get deprecation warnings on compilation so its recommended to migrate your code to use
the equivalent `SupervisionStrategy` as described earlier.

2
docs/src/main/paradox/release-notes/index.md
View file

@ -12,7 +12,7 @@ This is milestone release and is aimed at testing some new support for users who
* Change the manager name to use `pekko` in the name ([PR587](https://github.com/apache/incubator-pekko/pull/587))
* Support interacting with Akka Remote and Cluster nodes ([PR765](https://github.com/apache/incubator-pekko/pull/765), [PR1112](https://github.com/apache/incubator-pekko/pull/1112))
* See the [wiki notes](https://cwiki.apache.org/confluence/display/PEKKO/Pekko+Akka+Compatibility) about uptaking this
* See the [wiki notes](https://cwiki.apache.org/confluence/display/PEKKO/Pekko+Akka+Compatibility) about uptaking this
* Change noisy logging in DNS handler ([PR835](https://github.com/apache/incubator-pekko/pull/835))
* Support reading akka-persistence snapshots ([PR837](https://github.com/apache/incubator-pekko/pull/837), [PR841](https://github.com/apache/incubator-pekko/pull/841))
* Fix deprecation version on GraphApply ([PR877](https://github.com/apache/incubator-pekko/pull/877))

2
stream-tests/src/test/scala/org/apache/pekko/stream/scaladsl/FlowFlatMapPrefixSpec.scala
View file

@ -714,7 +714,7 @@ class FlowFlatMapPrefixSpec extends StreamSpec("pekko.loglevel = debug") {
}
}
def withAttr[A] = Flow.fromGraph(new WithAttr[A])
"baseline behaviour" in {
"baseline behavior" in {
Source
.single("1")
.via(withAttr)

4
stream-tests/src/test/scala/org/apache/pekko/stream/scaladsl/FlowFutureFlowSpec.scala
View file

@ -29,9 +29,9 @@ class FlowFutureFlowSpec extends StreamSpec {
case x => x
}
// this stage's behaviour in case of an 'early' downstream cancellation is governed by an attribute
// this stage's behavior in case of an 'early' downstream cancellation is governed by an attribute
// so we run all tests cases using both modes of the attributes.
// please notice most of the cases don't exhibit any difference in behaviour between the two modes
// please notice most of the cases don't exhibit any difference in behavior between the two modes
for {
(att, name) <- List(
(Attributes.NestedMaterializationCancellationPolicy.EagerCancellation, "EagerCancellation"),

2
stream-tests/src/test/scala/org/apache/pekko/stream/scaladsl/LazyFlowSpec.scala
View file

@ -227,7 +227,7 @@ class LazyFlowSpec extends StreamSpec("""
val deferredMatVal = result._1
val list = result._2
list.failed.futureValue shouldBe a[TE]
// futureFlow's behaviour in case of mat failure (follows flatMapPrefix)
// futureFlow's behavior in case of mat failure (follows flatMapPrefix)
deferredMatVal.failed.futureValue shouldBe a[NeverMaterializedException]
deferredMatVal.failed.futureValue.getCause shouldEqual TE("mat-failed")
}

2
stream/src/main/scala/org/apache/pekko/stream/Attributes.scala
View file

@ -551,7 +551,7 @@ object Attributes {
/**
* Nested materialization cancellation strategy provides a way to configure the cancellation behavior of stages that materialize a nested flow.
*
* When cancelled before materializing their nested flows, these stages can either immediately cancel (default behaviour) without materializing the nested flow
* When cancelled before materializing their nested flows, these stages can either immediately cancel (default behavior) without materializing the nested flow
* or wait for the nested flow to materialize and then propagate the cancellation signal through it.
*
* This applies to [[pekko.stream.scaladsl.FlowOps.flatMapPrefix]], [[pekko.stream.scaladsl.Flow.futureFlow]] (and derivations such as [[pekko.stream.scaladsl.Flow.lazyFutureFlow]]).

2
stream/src/main/scala/org/apache/pekko/stream/javadsl/Flow.scala
View file

@ -1078,7 +1078,7 @@ final class Flow[In, Out, Mat](delegate: scaladsl.Flow[In, Out, Mat]) extends Gr
*
* Parallelism limits the number of how many asks can be "in flight" at the same time.
* Please note that the elements emitted by this operator are in-order with regards to the asks being issued
* (i.e. same behaviour as mapAsync).
* (i.e. same behavior as mapAsync).
*
* The operator fails with an [[pekko.stream.WatchedActorTerminatedException]] if the target actor is terminated.
*

2
stream/src/main/scala/org/apache/pekko/stream/javadsl/FlowWithContext.scala
View file

@ -57,7 +57,7 @@ final class FlowWithContext[In, CtxIn, Out, CtxOut, +Mat](
* Transform this flow by the regular flow. The given flow must support manual context propagation by
* taking and producing tuples of (data, context).
*
* It is up to the implementer to ensure the inner flow does not exhibit any behaviour that is not expected
* It is up to the implementer to ensure the inner flow does not exhibit any behavior that is not expected
* by the downstream elements, such as reordering. For more background on these requirements
* see https://pekko.apache.org/docs/pekko/current/stream/stream-context.html.
*

2
stream/src/main/scala/org/apache/pekko/stream/javadsl/Source.scala
View file

@ -2792,7 +2792,7 @@ final class Source[Out, Mat](delegate: scaladsl.Source[Out, Mat]) extends Graph[
*
* Parallelism limits the number of how many asks can be "in flight" at the same time.
* Please note that the elements emitted by this operator are in-order with regards to the asks being issued
* (i.e. same behaviour as mapAsync).
* (i.e. same behavior as mapAsync).
*
* The operator fails with an [[pekko.stream.WatchedActorTerminatedException]] if the target actor is terminated.
*

2
stream/src/main/scala/org/apache/pekko/stream/javadsl/SourceWithContext.scala
View file

@ -55,7 +55,7 @@ final class SourceWithContext[+Out, +Ctx, +Mat](delegate: scaladsl.SourceWithCon
* Transform this flow by the regular flow. The given flow must support manual context propagation by
* taking and producing tuples of (data, context).
*
* It is up to the implementer to ensure the inner flow does not exhibit any behaviour that is not expected
* It is up to the implementer to ensure the inner flow does not exhibit any behavior that is not expected
* by the downstream elements, such as reordering. For more background on these requirements
* see https://pekko.apache.org/docs/pekko/current/stream/stream-context.html.
*

26
stream/src/main/scala/org/apache/pekko/stream/scaladsl/Flow.scala
View file

@ -638,8 +638,8 @@ object Flow {
*
* '''Cancels when''' downstream cancels (see below)
*
* The operator's default behaviour in case of downstream cancellation before nested flow materialization (future completion) is to cancel immediately.
* This behaviour can be controlled by setting the [[pekko.stream.Attributes.NestedMaterializationCancellationPolicy.PropagateToNested]] attribute,
* The operator's default behavior in case of downstream cancellation before nested flow materialization (future completion) is to cancel immediately.
* This behavior can be controlled by setting the [[pekko.stream.Attributes.NestedMaterializationCancellationPolicy.PropagateToNested]] attribute,
* this will delay downstream cancellation until nested flow's materialization which is then immediately cancelled (with the original cancellation cause).
*/
@deprecated(
@ -670,8 +670,8 @@ object Flow {
*
* '''Cancels when''' downstream cancels (see below)
*
* The operator's default behaviour in case of downstream cancellation before nested flow materialization (future completion) is to cancel immediately.
* This behaviour can be controlled by setting the [[pekko.stream.Attributes.NestedMaterializationCancellationPolicy.PropagateToNested]] attribute,
* The operator's default behavior in case of downstream cancellation before nested flow materialization (future completion) is to cancel immediately.
* This behavior can be controlled by setting the [[pekko.stream.Attributes.NestedMaterializationCancellationPolicy.PropagateToNested]] attribute,
* this will delay downstream cancellation until nested flow's materialization which is then immediately cancelled (with the original cancellation cause).
*/
@deprecated("Use 'Flow.lazyFutureFlow' instead", "Akka 2.6.0")
@ -688,8 +688,8 @@ object Flow {
* The materialized future value is completed with the materialized value of the future flow or failed with a
* [[NeverMaterializedException]] if upstream fails or downstream cancels before the future has completed.
*
* The operator's default behaviour in case of downstream cancellation before nested flow materialization (future completion) is to cancel immediately.
* This behaviour can be controlled by setting the [[pekko.stream.Attributes.NestedMaterializationCancellationPolicy.PropagateToNested]] attribute,
* The operator's default behavior in case of downstream cancellation before nested flow materialization (future completion) is to cancel immediately.
* This behavior can be controlled by setting the [[pekko.stream.Attributes.NestedMaterializationCancellationPolicy.PropagateToNested]] attribute,
* this will delay downstream cancellation until nested flow's materialization which is then immediately cancelled (with the original cancellation cause).
*/
def futureFlow[I, O, M](flow: Future[Flow[I, O, M]]): Flow[I, O, Future[M]] =
@ -716,8 +716,8 @@ object Flow {
*
* '''Cancels when''' downstream cancels (see below)
*
* The operator's default behaviour in case of downstream cancellation before nested flow materialization (future completion) is to cancel immediately.
* This behaviour can be controlled by setting the [[pekko.stream.Attributes.NestedMaterializationCancellationPolicy.PropagateToNested]] attribute,
* The operator's default behavior in case of downstream cancellation before nested flow materialization (future completion) is to cancel immediately.
* This behavior can be controlled by setting the [[pekko.stream.Attributes.NestedMaterializationCancellationPolicy.PropagateToNested]] attribute,
* this will delay downstream cancellation until nested flow's materialization which is then immediately cancelled (with the original cancellation cause).
*/
def lazyFlow[I, O, M](create: () => Flow[I, O, M]): Flow[I, O, Future[M]] =
@ -744,8 +744,8 @@ object Flow {
*
* '''Cancels when''' downstream cancels (see below)
*
* The operator's default behaviour in case of downstream cancellation before nested flow materialization (future completion) is to cancel immediately.
* This behaviour can be controlled by setting the [[pekko.stream.Attributes.NestedMaterializationCancellationPolicy.PropagateToNested]] attribute,
* The operator's default behavior in case of downstream cancellation before nested flow materialization (future completion) is to cancel immediately.
* This behavior can be controlled by setting the [[pekko.stream.Attributes.NestedMaterializationCancellationPolicy.PropagateToNested]] attribute,
* this will delay downstream cancellation until nested flow's materialization which is then immediately cancelled (with the original cancellation cause).
*/
def lazyFutureFlow[I, O, M](create: () => Future[Flow[I, O, M]]): Flow[I, O, Future[M]] =
@ -1405,7 +1405,7 @@ trait FlowOps[+Out, +Mat] {
*
* Parallelism limits the number of how many asks can be "in flight" at the same time.
* Please note that the elements emitted by this operator are in-order with regards to the asks being issued
* (i.e. same behaviour as mapAsync).
* (i.e. same behavior as mapAsync).
*
* The operator fails with an [[pekko.stream.WatchedActorTerminatedException]] if the target actor is terminated,
* or with an [[java.util.concurrent.TimeoutException]] in case the ask exceeds the timeout passed in.
@ -2398,8 +2398,8 @@ trait FlowOps[+Out, +Mat] {
* the resulting flow will be materialized and signalled for upstream completion, it can then complete or continue to emit elements at its own discretion.
*
* '''Cancels when''' the materialized flow cancels.
* When downstream cancels before materialization of the nested flow, the operator's default behaviour is to cancel immediately,
* this behaviour can be controlled by setting the [[pekko.stream.Attributes.NestedMaterializationCancellationPolicy]] attribute on the flow.
* When downstream cancels before materialization of the nested flow, the operator's default behavior is to cancel immediately,
* this behavior can be controlled by setting the [[pekko.stream.Attributes.NestedMaterializationCancellationPolicy]] attribute on the flow.
* When this attribute is configured to true, downstream cancellation is delayed until the nested flow's materialization which is then immediately cancelled (with the original cancellation cause).
*
* @param n the number of elements to accumulate before materializing the downstream flow.

4
stream/src/main/scala/org/apache/pekko/stream/scaladsl/FlowWithContextOps.scala
View file

@ -43,7 +43,7 @@ trait FlowWithContextOps[+Out, +Ctx, +Mat] {
* Transform this flow by the regular flow. The given flow must support manual context propagation by
* taking and producing tuples of (data, context).
*
* It is up to the implementer to ensure the inner flow does not exhibit any behaviour that is not expected
* It is up to the implementer to ensure the inner flow does not exhibit any behavior that is not expected
* by the downstream elements, such as reordering. For more background on these requirements
* see https://pekko.apache.org/docs/pekko/current/stream/stream-context.html.
*
@ -73,7 +73,7 @@ trait FlowWithContextOps[+Out, +Ctx, +Mat] {
* Transform this flow by the regular flow. The given flow must support manual context propagation by
* taking and producing tuples of (data, context).
*
* It is up to the implementer to ensure the inner flow does not exhibit any behaviour that is not expected
* It is up to the implementer to ensure the inner flow does not exhibit any behavior that is not expected
* by the downstream elements, such as reordering. For more background on these requirements
* see https://pekko.apache.org/docs/pekko/current/stream/stream-context.html.
*