This is an automated email from the ASF dual-hosted git repository.
He-Pin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pekko.git
The following commit(s) were added to refs/heads/main by this push:
new 2ca08f43db docs: fix outdated content and wrong config keys and API
names (#3583)
2ca08f43db is described below
commit 2ca08f43db7956712004c29df5923812969256b9
Author: PJ Fanning <[email protected]>
AuthorDate: Fri Oct 9 07:40:48 2026 +0100
docs: fix outdated content and wrong config keys and API names (#3583)
* docs: fix outdated content and wrong config keys and API names
Motivation:
A review of the docs found statements that are out of date for Pekko
2.0 (JDK 8 advice, removed features described as current, old build
tool versions and syntax, deprecated APIs described as the main way)
and config keys, class names and method names that do not exist and
would fail if copied.
Modification:
- Outdated for 2.0: auto-down, the pekko-cluster script, async-dns
default, binary compatibility and may-change notes, container JVM
flags, packaging tool versions and Gradle Shadow snippets, Lombok
version, typesafehub links, Java 8/9 qualifiers and javadoc links,
sbt colon/`in` syntax and procedure syntax in multi-jvm testing,
JDK paths in multi-node testing, LevelDB dependencies, Props.create,
Akka version references, the SecurityManager UDP note, pre-fork
issue and Activator links, the pre-1.0 Pekko Management migration
section, the -2.3 sharding data flag, Java pattern matching
versions, stream docs (MaterializedMap, flatMap note, mapConcat
signatures, stubs, SI-2712/Dotty, deprecated Source.queue prose,
TestSink/TestSource.probe, Source.actorRef completion,
Sink.collection Factory, ActorFlow timeout exception,
javaCollectorParallelUnordered description)
- Wrong config keys: auto-start-journals/snapshot-stores values,
classic retry-gate-closed-for, artery canonical port, failure
detector implementation-class, aeron-dir, actor.provider, extension
FQCNs, monitored-by-nr-of-members default, stash-capacity default,
JMX MBean name
- Wrong API names: ProducerController, CurrentShardRegionState,
extractShardId, Backoff options, DeleteFailure/StoreFailure,
RefreshInterval, typed ActorSystem, pekko-cluster-typed artifact,
Pekko Projections version, Compression.inflate, RunnableGraph and
BidiFlow in stream composition
Result:
The docs match the 2.0 code and copied config/API names work.
Tests:
- Not run - docs only
References:
None - found during a review of the docs
* docs: fix blocking-io-dispatcher key in mapWithResource and
fromOutputStream
Motivation:
The mapWithResource and fromOutputStream operator pages give the
blocking dispatcher setting as
org.apache.pekko.stream.materializer.blocking-io-dispatcher, which does
not exist, and call these operators a Source.
Modification:
Use pekko.stream.materializer.blocking-io-dispatcher, and call them a
Flow and a Sink.
Result:
The documented key matches stream reference.conf.
Tests:
- Not run - docs only
References:
Refs #3586
* docs: fix more wrong facts, settings and API names
Motivation:
More doc pages state facts, settings and API names that do not match
the code.
Modification:
- remoting.md: classic remoting needs netty-transport and netty-handler
- cluster-metrics.md: name moving-average-half-life and link this page
- routing.md: fork-join-executor
- split-brain-resolver.md: stable-after; keep-majority is described above
- logging.md: dead letter logging during shutdown is off by default
- persistence-schema-evolution.md: Java serialization is disabled by
default
- fsm.md: UnsubscribeTransitionCallBack
- testing.md: ignoreNoMsg, int, remove duplicated sentence
- persistence-query.md: getReadJournalFor, Offset, newer events, title,
ReadJournalProvider label
- io-udp.md: Udp.Bind in Scala
- includes/cluster.md: remembered entities
- discovery/index.md: _service._tcp.pekko.test
- general/addressing.md: root down
- project/downstream-upgrade-strategy.md: patch example 1.1.1
- common/circuitbreaker.md: not an actor; CompletionStage
- typed/dispatchers.md:
org.apache.pekko.dispatch.ExecutorServiceConfigurator
- ExtensionDocSpec.scala (typed/extending.md snippet): real DatabasePool
class name
- typed/guide/tutorial_1.md: typed tell takes one argument
- typed/durable-state/persistence.md: DurableStateBehavior names, state
not events
- typed/mailboxes.md: fromConfig selects a mailbox; classic Settings
- typed/routers.md: preferLocalRoutees is only for group routers
- typed/interaction-patterns.md: typed TimerScheduler links and
startTimer* names; askWithStatus links ActorContext
- typed/replicated-eventsourcing-auction.md: WinnerDecided, Finish
Result:
These pages match the code.
Tests:
- Not run - docs only (plus a string in a doc snippet source)
References:
None - found during a review of the docs
* docs: fix StatusReply.ack javadoc anchor and fromOutputStream result
Motivation:
Two fixes were held back from #3587 because they touch files this PR
also changes.
Modification:
- typed/interaction-patterns.md: the Java StatusReply.ack() link used a
Scaladoc-style StatusReply$ target; use pekko.pattern.StatusReply#ack()
- StreamConverters/fromOutputStream.md: the IOResult carries the number
of bytes written, not the size of a file (OutputStreamGraphStage)
Result:
The link resolves and the description matches the code.
Tests:
- Not run - docs only
References:
Refs #3587
* docs: fix typos next to lines changed in this PR
Motivation:
#3588 fixes typos across the docs but skipped the ones next to lines
this PR changes, to avoid merge conflicts.
Modification:
- split-brain-resolver.md: stray asterisk, "its self" -> "itself"
- discovery/index.md: "which i configured" -> "which is configured",
"which two hosts" -> "with two hosts"
Result:
These typos are fixed without conflicting with #3588.
Tests:
- Not run - docs only
References:
Refs #3588
* docs: keep -2.3 in the RemoveInternalClusterShardingData example
* docs: fix the broken Array[Byte] scaladoc link and the leftover
observed-removed typo
---------
Co-authored-by: 虎鸣 <[email protected]>
---
.../pekko/typed/extensions/ExtensionDocSpec.scala | 2 +-
docs/src/main/paradox/additional/deploying.md | 3 +-
docs/src/main/paradox/additional/operations.md | 2 +-
docs/src/main/paradox/additional/packaging.md | 39 ++++++++++------
docs/src/main/paradox/cluster-client.md | 4 +-
docs/src/main/paradox/cluster-metrics.md | 4 +-
docs/src/main/paradox/cluster-sharding.md | 4 +-
docs/src/main/paradox/cluster-usage.md | 10 ++--
.../paradox/common/binary-compatibility-rules.md | 2 +-
docs/src/main/paradox/common/circuitbreaker.md | 8 ++--
docs/src/main/paradox/common/may-change.md | 2 +-
docs/src/main/paradox/coordinated-shutdown.md | 2 +-
docs/src/main/paradox/discovery/index.md | 25 ++--------
docs/src/main/paradox/dispatchers.md | 6 +--
docs/src/main/paradox/distributed-pub-sub.md | 7 ---
docs/src/main/paradox/fault-tolerance.md | 4 +-
docs/src/main/paradox/fsm.md | 2 +-
docs/src/main/paradox/general/addressing.md | 2 +-
docs/src/main/paradox/general/configuration.md | 8 ++--
docs/src/main/paradox/includes/cluster.md | 4 +-
docs/src/main/paradox/io-dns.md | 2 +-
docs/src/main/paradox/io-udp.md | 12 +----
docs/src/main/paradox/io.md | 2 +-
docs/src/main/paradox/logging.md | 4 +-
docs/src/main/paradox/multi-jvm-testing.md | 36 +++++++--------
docs/src/main/paradox/multi-node-testing.md | 12 ++---
docs/src/main/paradox/persistence-plugins.md | 15 ++++--
docs/src/main/paradox/persistence-query-leveldb.md | 6 +--
docs/src/main/paradox/persistence-query.md | 10 ++--
.../main/paradox/persistence-schema-evolution.md | 6 ++-
docs/src/main/paradox/persistence.md | 2 +-
.../paradox/project/downstream-upgrade-strategy.md | 2 +-
docs/src/main/paradox/project/immutable.md | 2 +-
docs/src/main/paradox/remoting-artery.md | 2 +-
docs/src/main/paradox/remoting.md | 9 ++--
docs/src/main/paradox/routing.md | 2 +-
docs/src/main/paradox/split-brain-resolver.md | 14 +++---
docs/src/main/paradox/stream/actor-interop.md | 54 +++++++++-------------
.../main/paradox/stream/operators/ActorFlow/ask.md | 2 +-
.../stream/operators/ActorFlow/askWithContext.md | 2 +-
.../stream/operators/ActorFlow/askWithStatus.md | 2 +-
.../operators/ActorFlow/askWithStatusAndContext.md | 2 +-
.../stream/operators/Compression/inflate.md | 2 +-
.../paradox/stream/operators/Sink/collection.md | 4 +-
.../operators/Source-or-Flow/mapWithResource.md | 4 +-
.../paradox/stream/operators/Source/actorRef.md | 14 +++---
.../operators/StreamConverters/fromOutputStream.md | 6 +--
.../javaCollectorParallelUnordered.md | 17 ++++++-
docs/src/main/paradox/stream/stream-composition.md | 6 +--
docs/src/main/paradox/stream/stream-cookbook.md | 2 +-
docs/src/main/paradox/stream/stream-customize.md | 18 ++++----
.../main/paradox/stream/stream-flows-and-basics.md | 18 ++++----
docs/src/main/paradox/stream/stream-quickstart.md | 7 +--
docs/src/main/paradox/stream/stream-testkit.md | 6 +--
docs/src/main/paradox/supervision-classic.md | 4 +-
docs/src/main/paradox/testing.md | 9 ++--
docs/src/main/paradox/typed/actors.md | 4 +-
docs/src/main/paradox/typed/cluster-concepts.md | 2 +-
docs/src/main/paradox/typed/cluster.md | 4 +-
docs/src/main/paradox/typed/dispatchers.md | 8 ++--
docs/src/main/paradox/typed/distributed-data.md | 8 ++--
.../paradox/typed/durable-state/persistence.md | 6 +--
docs/src/main/paradox/typed/from-classic.md | 2 +-
docs/src/main/paradox/typed/guide/modules.md | 12 ++---
docs/src/main/paradox/typed/guide/tutorial_1.md | 2 +-
.../src/main/paradox/typed/interaction-patterns.md | 16 +++----
docs/src/main/paradox/typed/mailboxes.md | 4 +-
docs/src/main/paradox/typed/persistence.md | 4 +-
docs/src/main/paradox/typed/reliable-delivery.md | 4 +-
.../typed/replicated-eventsourcing-auction.md | 4 +-
docs/src/main/paradox/typed/routers.md | 4 +-
71 files changed, 267 insertions(+), 274 deletions(-)
diff --git
a/actor-typed-tests/src/test/scala/docs/org/apache/pekko/typed/extensions/ExtensionDocSpec.scala
b/actor-typed-tests/src/test/scala/docs/org/apache/pekko/typed/extensions/ExtensionDocSpec.scala
index 7e8b20a20c..a6c30febcd 100644
---
a/actor-typed-tests/src/test/scala/docs/org/apache/pekko/typed/extensions/ExtensionDocSpec.scala
+++
b/actor-typed-tests/src/test/scala/docs/org/apache/pekko/typed/extensions/ExtensionDocSpec.scala
@@ -55,7 +55,7 @@ class DatabasePool(system: ActorSystem[?]) extends Extension {
object ExtensionDocSpec {
val config = ConfigFactory.parseString("""
#config
- pekko.actor.typed.extensions =
["org.apache.pekko.pekko.extensions.DatabasePool"]
+ pekko.actor.typed.extensions =
["docs.org.apache.pekko.typed.extensions.DatabasePool"]
#config
""")
diff --git a/docs/src/main/paradox/additional/deploying.md
b/docs/src/main/paradox/additional/deploying.md
index 44dc335135..ec3c70d0cb 100644
--- a/docs/src/main/paradox/additional/deploying.md
+++ b/docs/src/main/paradox/additional/deploying.md
@@ -41,7 +41,8 @@ Docker allows [constraining each containers' resource
usage](https://docs.docker
#### Memory
-You may want to look into using `-XX:+UnlockExperimentalVMOptions
-XX:+UseCGroupMemoryLimitForHeap` options for your JVM later than 8u131, which
makes it understand c-group memory limits. On JVM 10 and later, the
`-XX:+UnlockExperimentalVMOptions` option is no longer needed.
+Modern JVMs are container aware: container support
(`-XX:+UseContainerSupport`) is enabled by default, so the JVM respects the
c-group memory limits of the container.
+By default the maximum heap size is only a fraction of the container memory
limit, so you may want to tune it with `-XX:MaxRAMPercentage`.
#### CPU
diff --git a/docs/src/main/paradox/additional/operations.md
b/docs/src/main/paradox/additional/operations.md
index 27b7c83926..1c8102102f 100644
--- a/docs/src/main/paradox/additional/operations.md
+++ b/docs/src/main/paradox/additional/operations.md
@@ -43,7 +43,7 @@ See documentation of @extref:[Pekko
Management](pekko-management:).
<a id="cluster-jmx"></a>
### JMX
-Information and management of the cluster is available as JMX MBeans with the
root name `org.apache.pekko.Cluster`.
+Information and management of the cluster is available as JMX MBeans with the
root name `pekko:type=Cluster` (or `pekko:type=Cluster,port=<port>` when
`pekko.cluster.jmx.multi-mbeans-in-same-jvm` is enabled).
The JMX information can be displayed with an ordinary JMX console such as
JConsole or JVisualVM.
From JMX you can:
diff --git a/docs/src/main/paradox/additional/packaging.md
b/docs/src/main/paradox/additional/packaging.md
index 37aae239d6..05b011f06b 100644
--- a/docs/src/main/paradox/additional/packaging.md
+++ b/docs/src/main/paradox/additional/packaging.md
@@ -13,7 +13,7 @@ contains a `reference.conf` resource with default values.
The method for ensuring `reference.conf` and other `*.conf` resources are
merged depends on the tooling you use to create the fat jar:
* sbt: as an application packaged with
[sbt-native-packager](https://github.com/sbt/sbt-native-packager)
- * Maven: as an application packaged with a bundler such as jarjar, onejar or
assembly
+ * Maven: using the Maven Shade plugin
* Gradle: using the Jar task from the Java plugin
## sbt: Native Packager
@@ -24,18 +24,18 @@ distributions of any type of application, including Pekko
applications.
Define sbt version in `project/build.properties` file:
```none
-sbt.version=1.3.12
+sbt.version=1.13.0
```
Add [sbt-native-packager](https://github.com/sbt/sbt-native-packager) in
`project/plugins.sbt` file:
```none
-addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "1.1.5")
+addSbtPlugin("com.github.sbt" % "sbt-native-packager" % "1.13.0")
```
Follow the instructions for the `JavaAppPackaging` in the [sbt-native-packager
plugin
documentation](https://sbt-native-packager.readthedocs.io/en/latest/archetypes/java_app/index.html).
-## Maven: jarjar, onejar or assembly
+## Maven: Shade plugin
You can use the [Apache Maven Shade
Plugin](https://maven.apache.org/plugins/maven-shade-plugin/)
support for [Resource
Transformers](https://maven.apache.org/plugins/maven-shade-plugin/examples/resource-transformers.html#AppendingTransformer)
@@ -47,7 +47,7 @@ The plugin configuration might look like this:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
- <version>1.5</version>
+ <version>3.6.2</version>
<executions>
<execution>
<id>shade-my-jar</id>
@@ -93,30 +93,41 @@ When using Gradle, you would typically use the
to create the fat jar.
To make sure the `reference.conf` resources are correctly merged, you might
-use the [Shadow plugin](https://imperceptiblethoughts.com/shadow/), which might
+use the [Shadow plugin](https://gradleup.com/shadow/), which might
look something like this:
```groovy
-import
com.github.jengelman.gradle.plugins.shadow.transformers.AppendingTransformer
-
plugins {
id 'java'
- id "com.github.johnrengelman.shadow" version "7.0.0"
+ id 'com.gradleup.shadow' version '9.6.1'
}
shadowJar {
append 'reference.conf'
append 'version.conf'
- with jar
+ // the default duplicates strategy (EXCLUDE) would drop all but the first
+ // copy of these files before they reach the append transformers
+ filesMatching(['reference.conf', 'version.conf']) {
+ duplicatesStrategy = DuplicatesStrategy.INCLUDE
+ }
}
```
Or when you use the Kotlin DSL:
```kotlin
-tasks.withType<ShadowJar> {
- val newTransformer = AppendingTransformer()
- newTransformer.resource = "reference.conf"
- transformers.add(newTransformer)
+plugins {
+ java
+ id("com.gradleup.shadow") version "9.6.1"
+}
+
+tasks.shadowJar {
+ append("reference.conf")
+ append("version.conf")
+ // the default duplicates strategy (EXCLUDE) would drop all but the first
+ // copy of these files before they reach the append transformers
+ filesMatching(listOf("reference.conf", "version.conf")) {
+ duplicatesStrategy = DuplicatesStrategy.INCLUDE
+ }
}
```
diff --git a/docs/src/main/paradox/cluster-client.md
b/docs/src/main/paradox/cluster-client.md
index e30091adb9..e68590b9f8 100644
--- a/docs/src/main/paradox/cluster-client.md
+++ b/docs/src/main/paradox/cluster-client.md
@@ -50,7 +50,7 @@ within the same cluster. Similar functionality as the
@apidoc[ClusterClient] is
provided more efficiently by @ref:[Distributed Publish Subscribe in
Cluster](distributed-pub-sub.md) for actors that
belong to the same cluster.
-The connecting system must have its `org.apache.pekko.actor.provider` set to
`remote` or `cluster` when using
+The connecting system must have its `pekko.actor.provider` set to `remote` or
`cluster` when using
the cluster client.
The receptionist is supposed to be started on all nodes, or all nodes with a
specified role,
@@ -163,7 +163,7 @@ It is recommended to load the extension when the actor
system is started by defi
`pekko.extensions` configuration property:
```
-pekko.extensions = ["pekko.cluster.client.ClusterClientReceptionist"]
+pekko.extensions =
["org.apache.pekko.cluster.client.ClusterClientReceptionist"]
```
## Events
diff --git a/docs/src/main/paradox/cluster-metrics.md
b/docs/src/main/paradox/cluster-metrics.md
index 44ad06b75a..a04937f59c 100644
--- a/docs/src/main/paradox/cluster-metrics.md
+++ b/docs/src/main/paradox/cluster-metrics.md
@@ -17,7 +17,7 @@ and add the following configuration stanza to your
`application.conf`
:
```
-pekko.extensions = [ "pekko.cluster.metrics.ClusterMetricsExtension" ]
+pekko.extensions = [
"org.apache.pekko.cluster.metrics.ClusterMetricsExtension" ]
```
@@project-info{ projectId="cluster-metrics" }
@@ -128,7 +128,7 @@ It can be configured to use a specific MetricsSelector to
produce the probabilit
* `mix` / `MixMetricsSelector` - Combines heap, cpu and load. Weights based on
mean of remaining capacity of the combined selectors.
* Any custom implementation of
`org.apache.pekko.cluster.metrics.MetricsSelector`
-The collected metrics values are smoothed with [exponential weighted moving
average](https://en.wikipedia.org/wiki/Moving_average#Exponential_moving_average).
In the @ref:[Cluster configuration](cluster-usage.md#cluster-configuration)
you can adjust how quickly past data is decayed compared to new data.
+The collected metrics values are smoothed with [exponential weighted moving
average](https://en.wikipedia.org/wiki/Moving_average#Exponential_moving_average).
With the `pekko.cluster.metrics.collector.moving-average-half-life` setting
(see @ref:[Configuration](#configuration)) you can adjust how quickly past data
is decayed compared to new data.
Let's take a look at this router in action. What can be more demanding than
calculating factorials?
diff --git a/docs/src/main/paradox/cluster-sharding.md
b/docs/src/main/paradox/cluster-sharding.md
index 616aff637b..e942f76e9a 100644
--- a/docs/src/main/paradox/cluster-sharding.md
+++ b/docs/src/main/paradox/cluster-sharding.md
@@ -167,7 +167,7 @@ for example with @ref:[Event Sourcing](persistence.md).
To make the list of entities in each `Shard` persistent (durable), set
the `rememberEntities` flag to true in `ClusterShardingSettings` when calling
-`ClusterSharding.start` and make sure the `shardIdExtractor` handles
+`ClusterSharding.start` and make sure the @scala[`extractShardId`
function]@java[`shardId` method of the `messageExtractor`] handles
`Shard.StartEntity(EntityId)` which implies that a `ShardId` must be possible
to
extract from the `EntityId`.
@@ -222,7 +222,7 @@ See @ref:[removal of Internal Cluster Sharding
Data](typed/cluster-sharding.md#r
Two requests to inspect the cluster state are available:
@scala[`ShardRegion.GetShardRegionState`]
@java[`ShardRegion.getShardRegionStateInstance`] which will return
-a @scala[`ShardRegion.CurrentShardRegionState`]
@java[`ShardRegion.ShardRegionState`] that contains
+a @scala[`ShardRegion.CurrentShardRegionState`]
@java[`ShardRegion.CurrentShardRegionState`] that contains
the identifiers of the shards running in a Region and what entities are alive
for each of them.
`ShardRegion.GetClusterShardingStats` which will query all the regions in the
cluster and return
diff --git a/docs/src/main/paradox/cluster-usage.md
b/docs/src/main/paradox/cluster-usage.md
index 24f9d4db43..85d4795f69 100644
--- a/docs/src/main/paradox/cluster-usage.md
+++ b/docs/src/main/paradox/cluster-usage.md
@@ -382,13 +382,15 @@ There are several management tools for the cluster.
Please refer to the
@@@ warning
-**Deprecation warning** - The command line script has been deprecated and is
scheduled for removal
-in the next major version. Use the @ref:[HTTP
management](additional/operations.md#http) API with [curl](https://curl.se/)
+**Deprecation warning** - The command line script has been deprecated and may
be removed
+in a future release. Use the @ref:[HTTP
management](additional/operations.md#http) API with [curl](https://curl.se/)
or similar instead.
@@@
-The cluster can be managed with the script `pekko-cluster` provided in the
Pekko GitHub repository @extref[here](github:cluster/jmx-client). Place the
script and the `jmxsh-R5.jar` library in the same directory.
+The cluster can be managed with the script `pekko-cluster` provided in the
Pekko GitHub repository @extref[here](github:cluster/jmx-client). The script
requires the `jmxsh-R5.jar` library, which is not shipped with Pekko. If the
jar is not present, the script
+attempts to download it with `curl` into the directory containing the script;
alternatively, obtain it separately and place it
+in the same directory as the script.
Run it without parameters to see instructions about how to use the script:
@@ -417,7 +419,7 @@ Examples: ./pekko-cluster localhost 9999 is-available
```
To be able to use the script you must enable remote monitoring and management
when starting the JVMs of the cluster nodes,
-as described in [Monitoring and Management Using JMX
Technology](https://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html).
+as described in [Monitoring and Management Using JMX
Technology](https://docs.oracle.com/en/java/javase/17/management/monitoring-and-management-using-jmx-technology.html).
Make sure you understand the security implications of enabling remote
monitoring and management.
<a id="cluster-configuration"></a>
diff --git a/docs/src/main/paradox/common/binary-compatibility-rules.md
b/docs/src/main/paradox/common/binary-compatibility-rules.md
index 8dd5646cf2..24518e6f06 100644
--- a/docs/src/main/paradox/common/binary-compatibility-rules.md
+++ b/docs/src/main/paradox/common/binary-compatibility-rules.md
@@ -56,7 +56,7 @@ Some modules are excluded from the binary compatibility
guarantees, such as:
Once a method has been deprecated then the guideline* is that it will be kept,
at minimum, for one **full** minor version release. For example, if it is
deprecated in version 1.0.2 then it will remain through the rest of 1.0, as
well as the entirety of 1.1.
-Methods that were deprecated in Akka, before the project fork to Pekko, are
being considered for removal in Pekko 1.1.0.
+Methods that were deprecated in Akka, before the project fork to Pekko, have
been removed in Pekko 2.0.0.
*This is a guideline because in **rare** instances, after careful
consideration, an exception may be made and the method removed earlier.
diff --git a/docs/src/main/paradox/common/circuitbreaker.md
b/docs/src/main/paradox/common/circuitbreaker.md
index ccca962ab8..d7606aa19a 100644
--- a/docs/src/main/paradox/common/circuitbreaker.md
+++ b/docs/src/main/paradox/common/circuitbreaker.md
@@ -80,9 +80,9 @@ Java
### Future & Synchronous based API
-Once a circuit breaker actor has been initialized, interacting with that actor
is done by either using the Future based API or the synchronous API. Both of
these APIs are considered `Call Protection` because whether synchronously or
asynchronously, the purpose of the circuit breaker is to protect your system
from cascading failures while making a call to another service. In the future
based API, we use the
@scala[@scaladoc[withCircuitBreaker](pekko.pattern.CircuitBreaker#withCircuitBreak
[...]
+Once a circuit breaker has been initialized, interacting with it is done by
either using the Future based API or the synchronous API. Both of these APIs
are considered `Call Protection` because whether synchronously or
asynchronously, the purpose of the circuit breaker is to protect your system
from cascading failures while making a call to another service. In the future
based API, we use the
@scala[@scaladoc[withCircuitBreaker](pekko.pattern.CircuitBreaker#withCircuitBreaker[T](body:=%3
[...]
-The Synchronous API would also wrap your call with the circuit breaker logic,
however, it uses the
@scala[@scaladoc[withSyncCircuitBreaker](pekko.pattern.CircuitBreaker#withSyncCircuitBreaker[T](body:=%3ET):T)]@java[@javadoc[callWithSyncCircuitBreaker](pekko.pattern.CircuitBreaker#callWithSyncCircuitBreaker(java.util.concurrent.Callable))]
and receives a method that is not wrapped in a
@scala[@scaladoc[Future](scala.concurrent.Future)]@java[@javadoc[CompletionState](java.util.concurrent.
[...]
+The Synchronous API would also wrap your call with the circuit breaker logic,
however, it uses the
@scala[@scaladoc[withSyncCircuitBreaker](pekko.pattern.CircuitBreaker#withSyncCircuitBreaker[T](body:=%3ET):T)]@java[@javadoc[callWithSyncCircuitBreaker](pekko.pattern.CircuitBreaker#callWithSyncCircuitBreaker(java.util.concurrent.Callable))]
and receives a method that is not wrapped in a
@scala[@scaladoc[Future](scala.concurrent.Future)]@java[@javadoc[CompletionStage](java.util.concurrent.
[...]
Scala
: @@snip
[CircuitBreakerDocSpec.scala](/docs/src/test/scala/docs/circuitbreaker/CircuitBreakerDocSpec.scala)
{ #circuit-breaker-usage }
@@ -94,14 +94,14 @@ Java
Using the @scala[@apidoc[CircuitBreaker](CircuitBreaker$)'s companion object
@scaladoc[apply](pekko.pattern.CircuitBreaker$#apply(scheduler:org.apache.pekko.actor.Scheduler,maxFailures:Int,callTimeout:scala.concurrent.duration.FiniteDuration,resetTimeout:scala.concurrent.duration.FiniteDuration):org.apache.pekko.pattern.CircuitBreaker)]@java[@javadoc[CircuitBreaker.create](pekko.pattern.CircuitBreaker#create(org.apache.pekko.actor.Scheduler,int,java.time.Duration,java.time.Duration))]
method
will return a @apidoc[CircuitBreaker] where callbacks are executed in the
caller's thread.
-This can be useful if the asynchronous
@scala[@scaladoc[Future](scala.concurrent.Future)]@java[@javadoc[CompletionState](java.util.concurrent.CompletionStage)]
behavior is unnecessary, for
+This can be useful if the asynchronous
@scala[@scaladoc[Future](scala.concurrent.Future)]@java[@javadoc[CompletionStage](java.util.concurrent.CompletionStage)]
behavior is unnecessary, for
example invoking a synchronous-only API.
@@@
### Control failure count explicitly
-By default, the circuit breaker treats
@javadoc[Exception](java.lang.Exception) as failure in synchronized API, or
failed
@scala[@scaladoc[Future](scala.concurrent.Future)]@java[@javadoc[CompletionState](java.util.concurrent.CompletionStage)]
as failure in future based API.
+By default, the circuit breaker treats
@javadoc[Exception](java.lang.Exception) as failure in synchronized API, or
failed
@scala[@scaladoc[Future](scala.concurrent.Future)]@java[@javadoc[CompletionStage](java.util.concurrent.CompletionStage)]
as failure in future based API.
On failure, the failure count will increment. If the failure count reaches the
*maxFailures*, the circuit breaker will be opened.
However, some applications may require certain exceptions to not increase the
failure count.
In other cases one may want to increase the failure count even if the call
succeeded.
diff --git a/docs/src/main/paradox/common/may-change.md
b/docs/src/main/paradox/common/may-change.md
index 854ae26400..160e7189f5 100644
--- a/docs/src/main/paradox/common/may-change.md
+++ b/docs/src/main/paradox/common/may-change.md
@@ -13,7 +13,7 @@ Concretely **may change** means that an API or module is in
early access mode an
Complete modules can be marked as **may change**, which will be stated in the
module's description and in the docs.
Individual public APIs can be annotated with
@javadoc[ApiMayChange](pekko.annotation.ApiMayChange) to signal that it has less
-guarantees than the rest of the module it lives in. For example, when while
introducing "new" Java 8 APIs into
+guarantees than the rest of the module it lives in. For example, when
introducing new APIs into
existing stable modules, these APIs may be marked with this annotation to
signal that they are not frozen yet.
Please use such methods and classes with care, however if you see such APIs
that is the best point in time to try them
out and provide feedback before they are frozen as fully stable API.
diff --git a/docs/src/main/paradox/coordinated-shutdown.md
b/docs/src/main/paradox/coordinated-shutdown.md
index f3658833ea..3b16b19ecd 100644
--- a/docs/src/main/paradox/coordinated-shutdown.md
+++ b/docs/src/main/paradox/coordinated-shutdown.md
@@ -55,7 +55,7 @@ Java
In the above example, it may be more convenient to simply stop the actor when
it's done shutting down, rather than send back a done message,
and for the shutdown task to not complete until the actor is terminated. A
convenience method is provided that adds a task that sends
-a message to the actor and then watches its termination (there is currently no
corresponding functionality for the new actors API @github[see #29056](#29056)):
+a message to the actor and then watches its termination (there is currently no
corresponding functionality for the new actors API):
Scala
: @@snip
[ActorDocSpec.scala](/docs/src/test/scala/docs/actor/ActorDocSpec.scala) {
#coordinated-shutdown-addActorTerminationTask }
diff --git a/docs/src/main/paradox/discovery/index.md
b/docs/src/main/paradox/discovery/index.md
index 8302dd311f..0b19c29cef 100644
--- a/docs/src/main/paradox/discovery/index.md
+++ b/docs/src/main/paradox/discovery/index.md
@@ -106,7 +106,7 @@ Lookups with all the fields set become SRV queries. For
example:
```
dig srv _service._tcp.pekko.test
-; <<>> DiG 9.11.3-RedHat-9.11.3-6.fc28 <<>> srv service.tcp.pekko.test
+; <<>> DiG 9.11.3-RedHat-9.11.3-6.fc28 <<>> srv _service._tcp.pekko.test
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 60023
@@ -116,7 +116,7 @@ dig srv _service._tcp.pekko.test
; EDNS: version: 0, flags:; udp: 4096
; COOKIE: 5ab8dd4622e632f6190f54de5b28bb8fb1b930a5333c3862 (good)
;; QUESTION SECTION:
-;service.tcp.pekko.test. IN SRV
+;_service._tcp.pekko.test. IN SRV
;; ANSWER SECTION:
_service._tcp.pekko.test. 86400 IN SRV 10 60 5060
a-single.pekko.test.
@@ -124,7 +124,7 @@ _service._tcp.pekko.test. 86400 IN SRV 10 40
5070 a-double.pekko.tes
```
-In this case `service.tcp.pekko.test` resolves to `a-single.pekko.test` on
port `5060`
+In this case `_service._tcp.pekko.test` resolves to `a-single.pekko.test` on
port `5060`
and `a-double.pekko.test` on port `5070`. Currently discovery does not support
the weightings.
#### A/AAAA records
@@ -235,20 +235,5 @@ pekko {
```
The above configuration will result in `pekko-dns` first being checked and if
it fails or returns no
-targets for the given service name then `config` is queried which i configured
with one service called
-`service1` which two hosts `host1` and `host2`.
-
-## Migrating from Pekko Management Discovery (before 1.0.0)
-
-Pekko Discovery started out as a submodule of Pekko Management, before 1.0.0
of Pekko Management. Pekko Discovery is not compatible with those versions of
Pekko Management Discovery.
-
-At least version `1.0.0` of any Pekko Management module should be used if also
using Pekko Discovery.
-
-Migration steps:
-
-* Any custom discovery method should now implement
`org.apache.pekko.discovery.ServiceDiscovery`
-* `discovery-method` now has to be a configuration location under
`pekko.discovery` with at minimum a property `class` specifying the fully
qualified name of the implementation of
`org.apache.pekko.discovery.ServiceDiscovery`.
- Previous versions allowed this to be a class name or a fully qualified
config location e.g. `pekko.discovery.kubernetes-api` rather than just
`kubernetes-api`
-
-
-
+targets for the given service name then `config` is queried which is
configured with one service called
+`service1` with two hosts `host1` and `host2`.
diff --git a/docs/src/main/paradox/dispatchers.md
b/docs/src/main/paradox/dispatchers.md
index ba28c97da1..099e5b9a11 100644
--- a/docs/src/main/paradox/dispatchers.md
+++ b/docs/src/main/paradox/dispatchers.md
@@ -40,9 +40,9 @@ is to configure the dispatcher:
Note that the `parallelism-max` does not set the upper bound on the total
number of threads
allocated by the ForkJoinPool. It is a setting specifically talking about the
number of *hot*
threads the pool keep running in order to reduce the latency of handling a new
incoming task.
-You can read more about parallelism in the JDK's [ForkJoinPool
documentation](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ForkJoinPool.html).
+You can read more about parallelism in the JDK's [ForkJoinPool
documentation](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/ForkJoinPool.html).
-When Running on Java 9+, you can use `maximum-pool-size` to set the upper
bound on the total number of threads allocated by the ForkJoinPool.
+You can use `maximum-pool-size` to set the upper bound on the total number of
threads allocated by the ForkJoinPool.
When running on Java 25+, the `minimum-runnable` setting for the
`fork-join-executor` defaults to a JDK-aware value
(`min(8, max(1, parallelism / 2))`) instead of the historical `1`. This raises
the number of compensation threads the
@@ -77,7 +77,7 @@ Another example that uses the "thread-pool-executor":
@@@ note
The thread pool executor dispatcher is implemented using a
@javadoc[java.util.concurrent.ThreadPoolExecutor](java.util.concurrent.ThreadPoolExecutor).
-You can read more about it in the JDK's [ThreadPoolExecutor
documentation](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ThreadPoolExecutor.html).
+You can read more about it in the JDK's [ThreadPoolExecutor
documentation](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/ThreadPoolExecutor.html).
@@@
diff --git a/docs/src/main/paradox/distributed-pub-sub.md
b/docs/src/main/paradox/distributed-pub-sub.md
index 6f51c55e9f..c729c7566d 100644
--- a/docs/src/main/paradox/distributed-pub-sub.md
+++ b/docs/src/main/paradox/distributed-pub-sub.md
@@ -50,13 +50,6 @@ any other node.
There are two different modes of message delivery, explained in the sections
@ref:[Publish](#distributed-pub-sub-publish) and
@ref:[Send](#distributed-pub-sub-send) below.
-@@@ div { .group-scala }
-
-A more comprehensive sample is available in the
-tutorial named [Pekko Clustered PubSub with
Scala!](https://github.com/typesafehub/activator-pekko-clustering).
-
-@@@
-
<a id="distributed-pub-sub-publish"></a>
## Publish
diff --git a/docs/src/main/paradox/fault-tolerance.md
b/docs/src/main/paradox/fault-tolerance.md
index 3df5a3cf5b..26d2def329 100644
--- a/docs/src/main/paradox/fault-tolerance.md
+++ b/docs/src/main/paradox/fault-tolerance.md
@@ -54,7 +54,7 @@ First off, it is a one-for-one strategy, meaning that each
child is treated
separately (an all-for-one strategy works very similarly, the only difference
is that any decision is applied to all children of the supervisor, not only the
failing one).
-In the above example, `10` and @scala[`1 minute`]@java[`Duration.create(1,
TimeUnit.MINUTES)`] are passed to the `maxNrOfRetries`
+In the above example, `10` and @scala[`1
minute`]@java[`Duration.ofMinutes(1)`] are passed to the `maxNrOfRetries`
and `withinTimeRange` parameters respectively, which means that the strategy
restarts a child up to 10 restarts per minute.
The child actor is stopped if the restart count exceeds `maxNrOfRetries`
during the `withinTimeRange` duration.
@@ -310,7 +310,7 @@ Java
### Customization
-The `org.apache.pekko.pattern.BackoffOnFailureOptions` and
`org.apache.pekko.pattern.BackoffOnRestartOptions` can be used to customize the
behavior of the back-off supervisor actor.
+The `org.apache.pekko.pattern.BackoffOnFailureOptions` and
`org.apache.pekko.pattern.BackoffOnStopOptions` can be used to customize the
behavior of the back-off supervisor actor.
Options are:
* `withAutoReset`: The backoff is reset if no failure/stop occurs within the
duration. This is the default behavior with `minBackoff` as default value
* `withManualReset`: The child must send `BackoffSupervisor.Reset` to its
backoff supervisor (parent)
diff --git a/docs/src/main/paradox/fsm.md b/docs/src/main/paradox/fsm.md
index 9abce6f6c2..0ba2962e3c 100644
--- a/docs/src/main/paradox/fsm.md
+++ b/docs/src/main/paradox/fsm.md
@@ -418,7 +418,7 @@ External monitors may be unregistered by sending
`UnsubscribeTransitionCallBack(actorRef)` to the `FSM` actor.
Stopping a listener will remove it from the subscription list. Subscriptions
may
-also be removed explicitly with `UnsubscribeTransitionCallback`.
+also be removed explicitly with `UnsubscribeTransitionCallBack`.
@@@ div { .group-scala }
diff --git a/docs/src/main/paradox/general/addressing.md
b/docs/src/main/paradox/general/addressing.md
index 0de7eae409..9b8e3f4e43 100644
--- a/docs/src/main/paradox/general/addressing.md
+++ b/docs/src/main/paradox/general/addressing.md
@@ -85,7 +85,7 @@ to the new incarnation even though they have the same path.
Each actor path has an address component, describing the protocol and location
by which the corresponding actor is reachable, followed by the names of the
-actors in the hierarchy from the root up. Examples are:
+actors in the hierarchy from the root down. Examples are:
```
"pekko://my-sys/user/service-a/worker1" // purely local
diff --git a/docs/src/main/paradox/general/configuration.md
b/docs/src/main/paradox/general/configuration.md
index 2a337e0c13..cf0ca16872 100644
--- a/docs/src/main/paradox/general/configuration.md
+++ b/docs/src/main/paradox/general/configuration.md
@@ -37,10 +37,10 @@ upon their presence in the `reference.conf` supplied with
the library in
question.
Highest precedence is given to overrides given as system properties, see [the
-HOCON
specification](https://github.com/typesafehub/config/blob/master/HOCON.md)
(near the
+HOCON specification](https://github.com/lightbend/config/blob/master/HOCON.md)
(near the
bottom). Also noteworthy is that the application configuration—which defaults
to `application`—may be overridden using the `config.resource` property
-(there are more, please refer to the [Config
docs](https://github.com/typesafehub/config/blob/master/README.md)).
+(there are more, please refer to the [Config
docs](https://github.com/lightbend/config/blob/master/README.md)).
@@@ note
@@ -131,7 +131,7 @@ pekko {
}
```
-More advanced include and substitution mechanisms are explained in the
[HOCON](https://github.com/typesafehub/config/blob/master/HOCON.md)
+More advanced include and substitution mechanisms are explained in the
[HOCON](https://github.com/lightbend/config/blob/master/HOCON.md)
specification.
<a id="dpekko-log-config-on-start"></a>
@@ -149,7 +149,7 @@ If in doubt, you can inspect your configuration objects
before or after using them to construct an actor system:
```
-Welcome to Scala 2.13 (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0).
+Welcome to Scala 2.13 (OpenJDK 64-Bit Server VM, Java 17).
Type in expressions to have them evaluated.
Type :help for more information.
diff --git a/docs/src/main/paradox/includes/cluster.md
b/docs/src/main/paradox/includes/cluster.md
index 06d7980635..027cd1fce4 100644
--- a/docs/src/main/paradox/includes/cluster.md
+++ b/docs/src/main/paradox/includes/cluster.md
@@ -59,8 +59,8 @@ Reliable delivery and flow control of messages between actors
in the Cluster.
<!--- #sharding-persistence-mode-deprecated --->
@@@ warning
-Persistence for state store mode is deprecated. It is recommended to migrate
to `ddata` for the coordinator state and if using replicated entities
-migrate to `eventsourced` for the replicated entities state.
+The `persistence` state store mode is deprecated. It is recommended to migrate
to `ddata` for the coordinator state and if using remembered entities
+migrate to `eventsourced` for the remembered entities state.
The data written by the deprecated `persistence` state store mode for
remembered entities can be read by the new remember entities `eventsourced`
mode.
diff --git a/docs/src/main/paradox/io-dns.md b/docs/src/main/paradox/io-dns.md
index d07a383cf0..dfc067a03a 100644
--- a/docs/src/main/paradox/io-dns.md
+++ b/docs/src/main/paradox/io-dns.md
@@ -43,7 +43,7 @@ There are currently two implementations:
* `inet-address` - Based on the JDK's `InetAddress`. Using this will be
subject to both the JVM's DNS cache and its built in one.
* `async-dns` - A native implementation of the DNS protocol that does not use
any JDK classes or caches.
-`inet-address` is the default implementation as it pre-dates `async-dns`,
`async-dns` will likely become the default in the next major release.
+`inet-address` is the default implementation as it pre-dates `async-dns`,
`async-dns` may become the default in a future release.
DNS lookups can be done via the `DNS` extension:
diff --git a/docs/src/main/paradox/io-udp.md b/docs/src/main/paradox/io-udp.md
index c81b41597f..5dbc8b68bd 100644
--- a/docs/src/main/paradox/io-udp.md
+++ b/docs/src/main/paradox/io-udp.md
@@ -99,16 +99,6 @@ Consequently the example shown here looks quite similar to
the previous one,
the biggest difference is the absence of remote address information in
@scala[`Send`]@java[`UdpMessage.send`] and `Received` messages.
-@@@ note
-
-There is a small performance benefit in using connection based UDP API over
-the connectionless one. If there is a SecurityManager enabled on the system,
-every connectionless message send has to go through a security check, while
-in the case of connection-based UDP the security check is cached after
-connect, thus writes do not suffer an additional performance penalty.
-
-@@@
-
## UDP Multicast
Pekko provides a way to control various options of `DatagramChannel` through
the
@@ -133,7 +123,7 @@ Scala
Java
: @@snip
[JavaUdpMulticast.java](/docs/src/test/java/jdocs/io/JavaUdpMulticast.java) {
#multicast-group }
-Socket options must be provided to
@scala[`UdpMessage.Bind`]@java[`UdpMessage.bind`] message.
+Socket options must be provided to @scala[`Udp.Bind`]@java[`UdpMessage.bind`]
message.
Scala
: @@snip
[ScalaUdpMulticast.scala](/docs/src/test/scala/docs/io/ScalaUdpMulticast.scala)
{ #bind }
diff --git a/docs/src/main/paradox/io.md b/docs/src/main/paradox/io.md
index dfd48cf633..ff15038400 100644
--- a/docs/src/main/paradox/io.md
+++ b/docs/src/main/paradox/io.md
@@ -92,7 +92,7 @@ not error handling. In other words, data may still be lost,
even if every write
To maintain isolation, actors should communicate with immutable objects only.
@apidoc[ByteString](util.ByteString) is an
immutable container for bytes. It is used by Pekko's I/O system as an
efficient, immutable alternative
-to the traditional byte containers used for I/O on the JVM, such as
@scala[@scaladoc[Array](scala.Array)[@scaladoc[Byte](scala.Byte)]]@java[`byte[]`]
and @javadoc[ByteBuffer](java.nio.ByteBuffer).
+to the traditional byte containers used for I/O on the JVM, such as
@scala[@scaladoc[Array[Byte]](scala.Array)]@java[`byte[]`] and
@javadoc[ByteBuffer](java.nio.ByteBuffer).
`ByteString` is a
[rope-like](https://en.wikipedia.org/wiki/Rope_\(computer_science\)) data
structure that is immutable
and provides fast concatenation and slicing operations (perfect for I/O). When
two `ByteString`s are concatenated
diff --git a/docs/src/main/paradox/logging.md b/docs/src/main/paradox/logging.md
index 8387dc0612..24ede3c807 100644
--- a/docs/src/main/paradox/logging.md
+++ b/docs/src/main/paradox/logging.md
@@ -94,8 +94,8 @@ does not necessarily indicate a problem, but they are logged
by default for the
After a few messages this logging is turned off, to avoid flooding the logs.
You can disable this logging completely or adjust how many dead letters are
logged. During system shutdown it is likely that you see dead letters, since
pending
-messages in the actor mailboxes are sent to dead letters. You can also disable
logging
-of dead letters during shutdown.
+messages in the actor mailboxes are sent to dead letters. Logging of dead
letters during shutdown is disabled by default,
+but it can be enabled.
```ruby
pekko {
diff --git a/docs/src/main/paradox/multi-jvm-testing.md
b/docs/src/main/paradox/multi-jvm-testing.md
index af18de732e..e9cf6d97a8 100644
--- a/docs/src/main/paradox/multi-jvm-testing.md
+++ b/docs/src/main/paradox/multi-jvm-testing.md
@@ -39,7 +39,7 @@ So in Pekko, to run all the multi-JVM tests in the
pekko-remote project use (at
the sbt prompt):
```none
-remote-tests/multi-jvm:test
+remote-tests / MultiJvm / test
```
Or one can change to the `pekko-remote-tests` project first, and then run the
@@ -47,13 +47,13 @@ tests:
```none
project remote-tests
-multi-jvm:test
+MultiJvm / test
```
To run individual tests use `testOnly`:
```none
-multi-jvm:testOnly org.apache.pekko.remote.RandomRoutedRemoteActor
+MultiJvm / testOnly org.apache.pekko.remote.RemoteDelivery
```
More than one test name can be listed to run multiple specific
@@ -63,7 +63,7 @@ It's also possible to specify JVM options with `testOnly` by
including those
options after the test names and `--`. For example:
```none
-multi-jvm:testOnly org.apache.pekko.remote.RandomRoutedRemoteActor --
-Dsome.option=something
+MultiJvm / testOnly org.apache.pekko.remote.RemoteDelivery --
-Dsome.option=something
```
## Creating application tests
@@ -87,29 +87,29 @@ like the following:
package sample
object SampleMultiJvmNode1 {
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
println("Hello from node 1")
}
}
object SampleMultiJvmNode2 {
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
println("Hello from node 2")
}
}
object SampleMultiJvmNode3 {
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
println("Hello from node 3")
}
}
```
-When you call `multi-jvm:run sample.Sample` at the sbt prompt, three JVMs will
be
+When you call `MultiJvm / run sample.Sample` at the sbt prompt, three JVMs
will be
spawned, one for each node. It will look like this:
```none
-> multi-jvm:run sample.Sample
+> MultiJvm / run sample.Sample
...
[info] * sample.Sample
[JVM-1] Hello from node 1
@@ -123,22 +123,22 @@ spawned, one for each node. It will look like this:
You can specify JVM options for the forked JVMs:
```
-jvmOptions in MultiJvm := Seq("-Xmx256M")
+MultiJvm / jvmOptions := Seq("-Xmx256M")
```
You can change the name of the multi-JVM test source directory by adding the
following
configuration to your project:
```none
-unmanagedSourceDirectories in MultiJvm :=
- Seq(baseDirectory(_ / "src/some_directory_here")).join.value
+MultiJvm / unmanagedSourceDirectories :=
+ Seq(baseDirectory.value / "src/some_directory_here")
```
You can change what the `MultiJvm` identifier is. For example, to change it to
`ClusterTest` use the `multiJvmMarker` setting:
```none
-multiJvmMarker in MultiJvm := "ClusterTest"
+MultiJvm / multiJvmMarker := "ClusterTest"
```
Your tests should now be named `{TestName}ClusterTest{NodeName}`.
@@ -149,26 +149,26 @@ You can define specific JVM options for each of the
spawned JVMs. You do that by
a file named after the node in the test with suffix `.opts` and put them in
the same
directory as the test.
-For example, to feed the JVM options `-Dpekko.remote.port=9991` and `-Xmx256m`
to the `SampleMultiJvmNode1`
+For example, to feed the JVM options
`-Dpekko.remote.artery.canonical.port=9991` and `-Xmx256m` to the
`SampleMultiJvmNode1`
let's create three `*.opts` files and add the options to them. Separate
multiple options with
space.
`SampleMultiJvmNode1.opts`:
```
--Dpekko.remote.port=9991 -Xmx256m
+-Dpekko.remote.artery.canonical.port=9991 -Xmx256m
```
`SampleMultiJvmNode2.opts`:
```
--Dpekko.remote.port=9992 -Xmx256m
+-Dpekko.remote.artery.canonical.port=9992 -Xmx256m
```
`SampleMultiJvmNode3.opts`:
```
--Dpekko.remote.port=9993 -Xmx256m
+-Dpekko.remote.artery.canonical.port=9993 -Xmx256m
```
## ScalaTest
@@ -203,7 +203,7 @@ class SpecMultiJvmNode2 extends AnyWordSpec with Matchers {
}
```
-To run just these tests you would call `multi-jvm:testOnly sample.Spec` at
+To run just these tests you would call `MultiJvm / testOnly sample.Spec` at
the sbt prompt.
## Multi Node Additions
diff --git a/docs/src/main/paradox/multi-node-testing.md
b/docs/src/main/paradox/multi-node-testing.md
index 6f4deb9674..2e133b5e87 100644
--- a/docs/src/main/paradox/multi-node-testing.md
+++ b/docs/src/main/paradox/multi-node-testing.md
@@ -130,11 +130,11 @@ Here are some examples of how you define hosts:
`user1@host1`
User `user1` on host `host1` with the default java.
*
- `user2@host2:/usr/lib/jvm/java-7-openjdk-amd64/bin/java`
- User `user2` on host `host2` using java 7.
+ `user2@host2:/usr/lib/jvm/java-17-openjdk-amd64/bin/java`
+ User `user2` on host `host2` using Java 17.
*
- `host3:/usr/lib/jvm/java-6-openjdk-amd64/bin/java`
- The current user on host `host3` using java 6.
+ `host3:/usr/lib/jvm/java-21-openjdk-amd64/bin/java`
+ The current user on host `host3` using Java 21.
### Running the Multi Node Tests
@@ -149,7 +149,7 @@ multiNodeTest
To run all of them in multi-jvm mode (i.e. all JVMs on the local machine) do:
```none
-multi-jvm:test
+MultiJvm / test
```
To run individual tests use the `multiNodeTestOnly` task:
@@ -161,7 +161,7 @@ multiNodeTestOnly your.MultiNodeTest
To run individual tests in the multi-jvm mode do:
```none
-multi-jvm:testOnly your.MultiNodeTest
+MultiJvm / testOnly your.MultiNodeTest
```
More than one test name can be listed to run multiple specific tests. Tab
completion in sbt makes it easy to
diff --git a/docs/src/main/paradox/persistence-plugins.md
b/docs/src/main/paradox/persistence-plugins.md
index e3f7162944..75dbd4e20d 100644
--- a/docs/src/main/paradox/persistence-plugins.md
+++ b/docs/src/main/paradox/persistence-plugins.md
@@ -45,12 +45,12 @@ pekko {
journal {
plugin = "pekko.persistence.journal.leveldb"
- auto-start-journals = ["org.apache.pekko.persistence.journal.leveldb"]
+ auto-start-journals = ["pekko.persistence.journal.leveldb"]
}
snapshot-store {
plugin = "pekko.persistence.snapshot-store.local"
- auto-start-snapshot-stores =
["org.apache.pekko.persistence.snapshot-store.local"]
+ auto-start-snapshot-stores = ["pekko.persistence.snapshot-store.local"]
}
}
@@ -79,7 +79,8 @@ defining config property:
@@snip
[PersistencePluginDocSpec.scala](/docs/src/test/scala/docs/persistence/PersistencePluginDocSpec.scala)
{ #leveldb-plugin-config }
-LevelDB based plugins will also require the following additional dependency
declaration:
+LevelDB based plugins will also require additional dependencies. With the
default setting `native = on`,
+the native LevelDB (via JNI) is used, which requires:
@@dependency[sbt,Maven,Gradle] {
group="org.fusesource.leveldbjni"
@@ -87,6 +88,14 @@ LevelDB based plugins will also require the following
additional dependency decl
version="1.8"
}
+With `native = off`, the LevelDB Java port is used, which requires:
+
+@@dependency[sbt,Maven,Gradle] {
+ group="org.iq80.leveldb"
+ artifact="leveldb"
+ version="0.12"
+}
+
The default location of LevelDB files is a directory named `journal` in the
current working
directory. This location can be changed by configuration where the specified
path can be relative or absolute:
diff --git a/docs/src/main/paradox/persistence-query-leveldb.md
b/docs/src/main/paradox/persistence-query-leveldb.md
index 2379e51d8f..d155bd87be 100644
--- a/docs/src/main/paradox/persistence-query-leveldb.md
+++ b/docs/src/main/paradox/persistence-query-leveldb.md
@@ -63,8 +63,7 @@ stored events is provided by `currentEventsByPersistenceId`.
The LevelDB write journal is notifying the query side as soon as events are
persisted, but for
efficiency reasons the query side retrieves the events in batches that
sometimes can
-be delayed up to the configured `refresh-interval` or given `RefreshInterval`
-hint.
+be delayed up to the configured `refresh-interval`.
The stream is completed with failure if there is a failure in executing the
query in the
backend journal.
@@ -145,8 +144,7 @@ stored events is provided by `currentEventsByTag`.
The LevelDB write journal is notifying the query side as soon as tagged events
are persisted, but for
efficiency reasons the query side retrieves the events in batches that
sometimes can
-be delayed up to the configured `refresh-interval` or given `RefreshInterval`
-hint.
+be delayed up to the configured `refresh-interval`.
The stream is completed with failure if there is a failure in executing the
query in the
backend journal.
diff --git a/docs/src/main/paradox/persistence-query.md
b/docs/src/main/paradox/persistence-query.md
index a85199a8fd..928860a7f4 100644
--- a/docs/src/main/paradox/persistence-query.md
+++ b/docs/src/main/paradox/persistence-query.md
@@ -1,7 +1,7 @@
---
project.description: Query side to Apache Pekko Persistence allowing for
building CQRS applications.
---
-# Apache Persistence Query
+# Pekko Persistence Query
## Dependency
@@ -59,7 +59,7 @@ Java
: @@snip
[PersistenceQueryDocTest.java](/docs/src/test/java/jdocs/persistence/PersistenceQueryDocTest.java)
{ #basic-usage }
Journal implementers are encouraged to put this identifier in a variable known
to the user, such that one can access it via
-@scala[@scaladoc[readJournalFor[NoopJournal](NoopJournal.identifier)](pekko.persistence.query.PersistenceQuery#readJournalFor[T%3C:org.apache.pekko.persistence.query.scaladsl.ReadJournal](readJournalPluginId:String):T)]@java[@javadoc[getJournalFor(NoopJournal.class,
NoopJournal.identifier)](pekko.persistence.query.PersistenceQuery#getReadJournalFor(java.lang.Class,java.lang.String))],
however this is not enforced.
+@scala[@scaladoc[readJournalFor[NoopJournal](NoopJournal.identifier)](pekko.persistence.query.PersistenceQuery#readJournalFor[T%3C:org.apache.pekko.persistence.query.scaladsl.ReadJournal](readJournalPluginId:String):T)]@java[@javadoc[getReadJournalFor(NoopJournal.class,
NoopJournal.identifier)](pekko.persistence.query.PersistenceQuery#getReadJournalFor(java.lang.Class,java.lang.String))],
however this is not enforced.
### Predefined queries
@@ -157,9 +157,9 @@ Java
As you can see, we can use all the usual stream operators available from
@ref:[Streams](stream/index.md) on the resulting query stream,
including for example taking the first 10 and cancelling the stream. It is
worth pointing out that the built-in `EventsByTag`
-query has an optionally supported offset parameter (of type `Long`) which the
journals can use to implement resumable-streams.
+query has an optionally supported offset parameter (of type `Offset`) which
the journals can use to implement resumable-streams.
For example a journal may be able to use a WHERE clause to begin the read
starting from a specific row, or in a datastore
-that is able to order events by insertion time it could treat the Long as a
timestamp and select only older events.
+that is able to order events by insertion time it could treat the offset as a
timestamp and select only newer events.
If your usage does not require a live stream, you can use the
@apidoc[currentEventsByTag](query.*.CurrentEventsByTagQuery) query.
@@ -289,7 +289,7 @@ their exposed semantics as well as handled query scenarios.
### ReadJournal plugin API
-A read journal plugin must implement
@apidoc[pekko.query.ReadJournalProvider](persistence.query.ReadJournalProvider)
which
+A read journal plugin must implement
@apidoc[pekko.persistence.query.ReadJournalProvider](persistence.query.ReadJournalProvider)
which
creates instances of
@scaladoc[pekko.persistence.query.scaladsl.ReadJournal](pekko.persistence.query.scaladsl.ReadJournal)
and
@javadoc[persistence.query.javadsl.ReadJournal](pekko.persistence.query.javadsl.ReadJournal).
The plugin must implement both the `scaladsl`
and the `javadsl` @scala[traits]@java[interfaces] because the
@scaladoc[pekko.stream.scaladsl.Source](pekko.stream.scaladsl.Source) and
diff --git a/docs/src/main/paradox/persistence-schema-evolution.md
b/docs/src/main/paradox/persistence-schema-evolution.md
index f44c23edeb..189b5f2150 100644
--- a/docs/src/main/paradox/persistence-schema-evolution.md
+++ b/docs/src/main/paradox/persistence-schema-evolution.md
@@ -138,7 +138,8 @@ user provided message itself, which we will from here on
refer to as the `payloa
Pekko Persistence provided serializers wrap the user payload in an envelope
containing all persistence-relevant information.
**If the Journal uses provided Protobuf serializers for the wrapper types
(e.g. PersistentRepr), then the payload will
-be serialized using the user configured serializer, and if none is provided
explicitly, Java serialization will be used for it.**
+be serialized using the user configured serializer. If none is provided
explicitly, the payload falls back to Java serialization, which is
+disabled by default (`pekko.actor.allow-java-serialization = off`), so
serialization of the payload will fail.**
The blue colored regions of the `PersistentMessage` indicate what is
serialized using the generated protocol buffers
serializers, and the yellow payload indicates the user provided event (by
calling
@scala[@scaladoc[persist(payload)(...)](pekko.persistence.PersistentActor#persist[A](event:A)(handler:A=%3EUnit):Unit)]@java[@javadoc[persist(payload,...)](pekko.persistence.AbstractPersistentActorLike#persist(A,org.apache.pekko.japi.Procedure))].
@@ -149,7 +150,8 @@ More advanced techniques (e.g. @ref:[Remove event class and
ignore events](#remo
flexibility of the persisted vs. exposed types even more. However for now we
will focus on the simpler evolution techniques,
concerning only configuring the payload serializers.
-By default the `payload` will be serialized using Java Serialization. This is
fine for testing and initial phases
+If no serializer is configured for it, the `payload` falls back to Java
Serialization, which is disabled by default
+(`pekko.actor.allow-java-serialization = off`). Enabling it may be acceptable
for testing and initial phases
of your development (while you're still figuring out things, and the data will
not need to stay persisted forever).
However, once you move to production you should really *pick a different
serializer for your payloads*.
diff --git a/docs/src/main/paradox/persistence.md
b/docs/src/main/paradox/persistence.md
index 9863508d3d..9035696442 100644
--- a/docs/src/main/paradox/persistence.md
+++ b/docs/src/main/paradox/persistence.md
@@ -859,7 +859,7 @@ in your Pekko configuration. Also note that for the LevelDB
Java port, you will
@@dependency[sbt,Maven,Gradle] {
group="org.iq80.leveldb"
artifact="leveldb"
- version="0.9"
+ version="0.12"
}
@@@ note
diff --git a/docs/src/main/paradox/project/downstream-upgrade-strategy.md
b/docs/src/main/paradox/project/downstream-upgrade-strategy.md
index d49db9c02a..f37927afa6 100644
--- a/docs/src/main/paradox/project/downstream-upgrade-strategy.md
+++ b/docs/src/main/paradox/project/downstream-upgrade-strategy.md
@@ -14,7 +14,7 @@ wait for intermediate libraries to update.
## Patch versions
-When releasing a new patch version of Pekko (e.g. 1.1.0), we typically don't
+When releasing a new patch version of Pekko (e.g. 1.1.1), we typically don't
immediately bump the Pekko version in satellite projects.
The reason for this is this will make it more low-friction for users to update
diff --git a/docs/src/main/paradox/project/immutable.md
b/docs/src/main/paradox/project/immutable.md
index 5f6fc1178d..07b599710a 100644
--- a/docs/src/main/paradox/project/immutable.md
+++ b/docs/src/main/paradox/project/immutable.md
@@ -24,7 +24,7 @@ To add Lombok to a Maven project, declare it as a simple
dependency:
@@dependency[Maven,Gradle] {
group="org.projectlombok"
artifact="lombok"
- version=1.18.10
+ version=1.18.48
}
# Using lombok
diff --git a/docs/src/main/paradox/remoting-artery.md
b/docs/src/main/paradox/remoting-artery.md
index da0247531c..3a0ea08813 100644
--- a/docs/src/main/paradox/remoting-artery.md
+++ b/docs/src/main/paradox/remoting-artery.md
@@ -634,7 +634,7 @@ aeron.threading.mode=SHARED_NETWORK
#aeron.sender.idle.strategy=org.agrona.concurrent.BusySpinIdleStrategy
#aeron.receiver.idle.strategy=org.agrona.concurrent.BusySpinIdleStrategy
-# use same director in pekko.remote.artery.advanced.aeron-dir config
+# use same directory in pekko.remote.artery.advanced.aeron.aeron-dir config
# of the Pekko application
aeron.dir=/dev/shm/aeron
```
diff --git a/docs/src/main/paradox/remoting.md
b/docs/src/main/paradox/remoting.md
index bce14fb3a9..0f53904cd7 100644
--- a/docs/src/main/paradox/remoting.md
+++ b/docs/src/main/paradox/remoting.md
@@ -40,8 +40,11 @@ not using classic remoting do not have to have Netty on the
classpath:
@@dependency[sbt,Maven,Gradle] {
group=io.netty
- artifact=netty
+ artifact=netty-transport
version=$netty_version$
+ group2=io.netty
+ artifact2=netty-handler
+ version2=$netty_version$
}
## Configuration
@@ -198,7 +201,7 @@ pekko {
```
The configuration above instructs Pekko to react when an actor with path
`/sampleActor` is created, i.e.
-using @scala[`system.actorOf(Props(...),
"sampleActor")`]@java[`system.actorOf(new Props(...), "sampleActor")`]. This
specific actor will not be directly instantiated,
+using @scala[`system.actorOf(Props(...),
"sampleActor")`]@java[`system.actorOf(Props.create(...), "sampleActor")`]. This
specific actor will not be directly instantiated,
but instead the remote daemon of the remote system will be asked to create the
actor,
which in this sample corresponds to `[email protected]:7356`.
@@ -302,7 +305,7 @@ is attempted to be sent to the remote system or an inbound
connection is accepte
When a communication failure happens and the connection is lost between the
two systems the link becomes `Gated`.
In this state the system will not attempt to connect to the remote host and
all outbound messages will be dropped. The time
-while the link is in the `Gated` state is controlled by the setting
`pekko.remote.retry-gate-closed-for`:
+while the link is in the `Gated` state is controlled by the setting
`pekko.remote.classic.retry-gate-closed-for`:
after this time elapses the link state transitions to `Idle` again. `Gate` is
one-sided in the
sense that whenever a successful *inbound* connection is accepted from a
remote system during `Gate` it automatically
transitions to `Active` and communication resumes immediately.
diff --git a/docs/src/main/paradox/routing.md b/docs/src/main/paradox/routing.md
index c51c0d997d..3f57d656a9 100644
--- a/docs/src/main/paradox/routing.md
+++ b/docs/src/main/paradox/routing.md
@@ -396,7 +396,7 @@ This is needed in order to implement the balancing
semantics via
sharing the same mailbox by all the routees.
While it is not possible to change the dispatcher used by the routees, it is
possible
-to fine tune the used *executor*. By default the `fork-join-dispatcher` is
used and
+to fine tune the used *executor*. By default the `fork-join-executor` is used
and
can be configured as explained in @ref:[Dispatchers](dispatchers.md). In
situations where the
routees are expected to perform blocking operations it may be useful to
replace it
with a `thread-pool-executor` hinting the number of allocated threads
explicitly:
diff --git a/docs/src/main/paradox/split-brain-resolver.md
b/docs/src/main/paradox/split-brain-resolver.md
index 4abc2374ac..ebd611da20 100644
--- a/docs/src/main/paradox/split-brain-resolver.md
+++ b/docs/src/main/paradox/split-brain-resolver.md
@@ -79,10 +79,10 @@ This works great for crashes and short transient network
partitions, but not for
partitions. Both sides of the network partition will see the other side as
unreachable and
after a while remove it from its cluster membership. Since this happens on
both sides the result
is that two separate disconnected clusters have been created.
-This approach is provided by the opt-in (off by default) auto-down feature in
the OSS version of
-Pekko Cluster.
+This approach was provided by the opt-in (off by default) auto-down feature,
which has been removed
+from Pekko Cluster.
-If you use the timeout based auto-down feature in combination with Cluster
Singleton or Cluster Sharding
+If such a timeout based auto-down approach were used in combination with
Cluster Singleton or Cluster Sharding
that would mean that two singleton instances or two sharded entities with the
same identifier would be running.
One would be running: one in each cluster.
For example when used together with Pekko Persistence that could result in
that two instances of a
@@ -264,8 +264,8 @@ There is another use of the `role` as well. By defining a
`role` for a few (e.g.
nodes in the cluster and using that in the configuration of `static-quorum`
you will be able
to dynamically add and remove other nodes without this role and still have
good decisions of what
nodes to keep running and what nodes to shut down in the case of network
partitions. The advantage
-of this approach compared to `keep-majority` (described below) is that you *do
not* risk splitting
-the cluster into two separate clusters, i.e. *a split brain**. You must still
obey the rule of not
+of this approach compared to `keep-majority` (described above) is that you *do
not* risk splitting
+the cluster into two separate clusters, i.e. *a split brain*. You must still
obey the rule of not
starting too many nodes with this `role` as described above. It also suffers
the risk of shutting
down all nodes if there is a failure when there are not enough nodes with this
`role` remaining
in the cluster, as described above.
@@ -459,8 +459,8 @@ Another concern for setting this
`stable-after`/`pekko.cluster.down-removal-marg
garbage collection. When a node is unresponsive it is not known if it is due
to a pause, overload, a crash or a
network partition. If it is pause that lasts longer than `stable-after` * 2 it
gives time for SBR to down the node
and for singletons and shards to be started on other nodes. When the node
un-pauses there will be a short time before
-it sees its self as down where singletons and sharded actors are still
running. It is therefore important to understand
-the max pause time your application is likely to incur and make sure it is
smaller than `stable-margin`.
+it sees itself as down where singletons and sharded actors are still running.
It is therefore important to understand
+the max pause time your application is likely to incur and make sure it is
smaller than `stable-after`.
If you choose to set a separate value for `down-removal-margin`, the
recommended minimum duration for different cluster sizes are:
diff --git a/docs/src/main/paradox/stream/actor-interop.md
b/docs/src/main/paradox/stream/actor-interop.md
index 0b04d99266..47792d4cfc 100644
--- a/docs/src/main/paradox/stream/actor-interop.md
+++ b/docs/src/main/paradox/stream/actor-interop.md
@@ -128,36 +128,21 @@ use `Sink.actorRefWithBackpressure` or `ask` in
`mapAsync`, though.
### Source.queue
-@@@ warning { title="Deprecation notice (since 2.0.0)" }
-
-The `Source.queue(Int, OverflowStrategy)` overloads that this section
describes — including `OverflowStrategy.backpressure` — are **deprecated**
because their asynchronous `offer` @scala[`Future`]@java[`CompletionStage`] can
hang indefinitely when downstream stalls. Use `Source.queue[T](bufferSize)`
(materializes a @apidoc[BoundedSourceQueue] with synchronous feedback), or for
backpressure towards the producer use
@ref:[`Source.actorRefWithBackpressure`](operators/Source/actorRefWithBack [...]
-
-The snippet below has been updated to the recommended non-deprecated API, so
it uses a synchronous `match`/`switch` on `QueueOfferResult` rather than the
`pipe`-the-`Future` pattern described in the surrounding prose.
-
-@@@
-
-`Source.queue` is an improvement over `Sink.actorRef`, since it can provide
backpressure.
-The `offer` method returns a @scala[`Future`]@java[`CompletionStage`], which
completes with the result of the enqueue operation.
-
`Source.queue` can be used for emitting elements to a stream from an actor (or
from anything running outside
-the stream). The elements will be buffered until the stream can process them.
You can `offer` elements to
-the queue and they will be emitted to the stream if there is demand from
downstream, otherwise they will
-be buffered until request for demand is received.
+the stream). `Source.queue[T](bufferSize)` materializes a
@apidoc[BoundedSourceQueue] which you can `offer` elements to.
+They will be emitted to the stream if there is demand from downstream,
otherwise they will be buffered until request
+for demand is received. Elements in the buffer will be discarded if downstream
is terminated.
-Use overflow strategy `org.apache.pekko.stream.OverflowStrategy.backpressure`
to avoid dropping of elements if the
-buffer is full, instead the returned @scala[`Future`]@java[`CompletionStage`]
does not complete until there is space in the
-buffer and `offer` should not be called again until it completes.
+Unlike `Source.actorRef`, `offer` gives immediate, synchronous feedback on
whether the element could be enqueued: it
+returns a `QueueOfferResult` which is `QueueOfferResult.Enqueued` if the
element was added to the buffer,
+`QueueOfferResult.Dropped` if the element was dropped because the buffer was
full, `QueueOfferResult.Failure` if the
+queue was failed, the stream failed or downstream cancelled, or
`QueueOfferResult.QueueClosed` if the queue was
+completed. Note that `Enqueued` does not guarantee that the element will be
processed by the rest of the stream.
+The caller decides how to handle a dropped element, for example by retrying
later or by signalling the producer to
+slow down.
-Using `Source.queue` you can push elements to the queue and they will be
emitted to the stream if there is
-demand from downstream, otherwise they will be buffered until request for
demand is received. Elements in the buffer
-will be discarded if downstream is terminated.
-
-You could combine it with the
@ref[`throttle`](operators/Source-or-Flow/throttle.md) operator is used to slow
down the stream to `5 element` per `3 seconds` and other patterns.
-
-`SourceQueue.offer` returns
@scala[`Future[QueueOfferResult]`]@java[`CompletionStage<QueueOfferResult>`]
which completes with `QueueOfferResult.Enqueued`
-if element was added to buffer or sent downstream. It completes with
`QueueOfferResult.Dropped` if element
-was dropped. Can also complete with `QueueOfferResult.Failure` - when stream
failed or
-`QueueOfferResult.QueueClosed` when downstream is completed.
+You could combine it with the
@ref[`throttle`](operators/Source-or-Flow/throttle.md) operator, which in the
example
+below slows down the stream to `5 elements` per `3 seconds`, and other
patterns.
Scala
: @@snip
[IntegrationDocSpec.scala](/docs/src/test/scala/docs/stream/IntegrationDocSpec.scala)
{ #source-queue }
@@ -165,8 +150,11 @@ Scala
Java
: @@snip
[IntegrationDocTest.java](/docs/src/test/java/jdocs/stream/IntegrationDocTest.java)
{ #source-queue }
-When used from an actor you typically `pipe` the result of the
@scala[`Future`]@java[`CompletionStage`] back to the actor to
-continue processing.
+@@@ note
+
+The `Source.queue(Int, OverflowStrategy)` overloads, which materialize a
`SourceQueueWithComplete` with an asynchronous `offer` returning a
@scala[`Future`]@java[`CompletionStage`], are **deprecated** (since 2.0.0)
because that @scala[`Future`]@java[`CompletionStage`] can hang indefinitely
when downstream stalls. If you need backpressure towards the producer use
@ref:[`Source.actorRefWithBackpressure`](operators/Source/actorRefWithBackpressure.md)
or `MergeHub.source` instead. See @ref:[ [...]
+
+@@@
### Source.actorRef
@@ -234,18 +222,18 @@ Sends the elements of the stream to the given
@java[`ActorRef<T>`]@scala[`ActorR
@@@
-### Topic.source
+### PubSub.source
A source that will subscribe to a @apidoc[actor.typed.pubsub.Topic$] and
stream messages published to the topic.
@@@ note
-See also: @ref[ActorSink.actorRefWithBackpressure operator reference
docs](operators/PubSub/source.md)
+See also: @ref[PubSub.source operator reference
docs](operators/PubSub/source.md)
@@@
-### Topic.sink
+### PubSub.sink
A sink that will publish emitted messages to a
@apidoc[actor.typed.pubsub.Topic$].
@@@ note
-See also: @ref[ActorSink.actorRefWithBackpressure operator reference
docs](operators/PubSub/sink.md)
+See also: @ref[PubSub.sink operator reference docs](operators/PubSub/sink.md)
@@@
diff --git a/docs/src/main/paradox/stream/operators/ActorFlow/ask.md
b/docs/src/main/paradox/stream/operators/ActorFlow/ask.md
index 5c2c6e8113..82511d7db8 100644
--- a/docs/src/main/paradox/stream/operators/ActorFlow/ask.md
+++ b/docs/src/main/paradox/stream/operators/ActorFlow/ask.md
@@ -24,7 +24,7 @@ This operator is included in:
## Description
Use the @ref[Ask
pattern](../../../typed/interaction-patterns.md#request-response-with-ask-from-outside-an-actor)
to send a request-reply message to the target `ref` actor.
-If any of the asks times out it will fail the stream with an
@apidoc[AskTimeoutException].
+If any of the asks times out it will fail the stream with a
`java.util.concurrent.TimeoutException`.
The `ask` operator requires
diff --git a/docs/src/main/paradox/stream/operators/ActorFlow/askWithContext.md
b/docs/src/main/paradox/stream/operators/ActorFlow/askWithContext.md
index 6359a4213f..845044b02e 100644
--- a/docs/src/main/paradox/stream/operators/ActorFlow/askWithContext.md
+++ b/docs/src/main/paradox/stream/operators/ActorFlow/askWithContext.md
@@ -26,7 +26,7 @@ This operator is included in:
Use the @ref[Ask
pattern](../../../typed/interaction-patterns.md#request-response-with-ask-from-outside-an-actor)
to send a request-reply message to the target `ref` actor.
The stream context is not sent, instead it is locally recombined to the
actor's reply.
-If any of the asks times out it will fail the stream with an
@apidoc[AskTimeoutException].
+If any of the asks times out it will fail the stream with a
`java.util.concurrent.TimeoutException`.
The `ask` operator requires
diff --git a/docs/src/main/paradox/stream/operators/ActorFlow/askWithStatus.md
b/docs/src/main/paradox/stream/operators/ActorFlow/askWithStatus.md
index bed53b6bc9..d030e7a63a 100644
--- a/docs/src/main/paradox/stream/operators/ActorFlow/askWithStatus.md
+++ b/docs/src/main/paradox/stream/operators/ActorFlow/askWithStatus.md
@@ -24,7 +24,7 @@ This operator is included in:
## Description
Use the @ref[Ask
pattern](../../../typed/interaction-patterns.md#request-response-with-ask-from-outside-an-actor)
to send a request-reply message to the target `ref` actor when you expect the
reply to be `org.apache.pekko.pattern.StatusReply`.
-If any of the asks times out it will fail the stream with an
@apidoc[AskTimeoutException].
+If any of the asks times out it will fail the stream with a
`java.util.concurrent.TimeoutException`.
The `askWithStatus` operator requires
diff --git
a/docs/src/main/paradox/stream/operators/ActorFlow/askWithStatusAndContext.md
b/docs/src/main/paradox/stream/operators/ActorFlow/askWithStatusAndContext.md
index 70e3519fdc..fafe105f1d 100644
---
a/docs/src/main/paradox/stream/operators/ActorFlow/askWithStatusAndContext.md
+++
b/docs/src/main/paradox/stream/operators/ActorFlow/askWithStatusAndContext.md
@@ -26,7 +26,7 @@ This operator is included in:
Use the @ref[Ask
pattern](../../../typed/interaction-patterns.md#request-response-with-ask-from-outside-an-actor)
to send a request-reply message to the target `ref` actor when you expect the
reply to be `org.apache.pekko.pattern.StatusReply`.
The stream context is not sent, instead it is locally recombined to the
actor's reply.
-If any of the asks times out it will fail the stream with an
@apidoc[AskTimeoutException].
+If any of the asks times out it will fail the stream with a
`java.util.concurrent.TimeoutException`.
The `ask` operator requires
diff --git a/docs/src/main/paradox/stream/operators/Compression/inflate.md
b/docs/src/main/paradox/stream/operators/Compression/inflate.md
index 843b2184e5..8de1840b6f 100644
--- a/docs/src/main/paradox/stream/operators/Compression/inflate.md
+++ b/docs/src/main/paradox/stream/operators/Compression/inflate.md
@@ -6,7 +6,7 @@ Creates a flow that deflate-decompresses a stream of
ByteStrings.
## Signature
-@apidoc[Compression.indeflate](stream.*.Compression$) {
scala="#inflate(maxBytesPerChunk:Int,nowrap:Boolean):org.apache.pekko.stream.scaladsl.Flow[org.apache.pekko.util.ByteString,org.apache.pekko.util.ByteString,org.apache.pekko.NotUsed]"
java="#inflate(int,boolean)" }
+@apidoc[Compression.inflate](stream.*.Compression$) {
scala="#inflate(maxBytesPerChunk:Int,nowrap:Boolean):org.apache.pekko.stream.scaladsl.Flow[org.apache.pekko.util.ByteString,org.apache.pekko.util.ByteString,org.apache.pekko.NotUsed]"
java="#inflate(int,boolean)" }
## Description
diff --git a/docs/src/main/paradox/stream/operators/Sink/collection.md
b/docs/src/main/paradox/stream/operators/Sink/collection.md
index b1627d148c..862ea375ab 100644
--- a/docs/src/main/paradox/stream/operators/Sink/collection.md
+++ b/docs/src/main/paradox/stream/operators/Sink/collection.md
@@ -8,11 +8,11 @@
## Signature
-@apidoc[Sink.collection](Sink$) {
scala="#collection[T,That](implicitcbf:org.apache.pekko.util.ccompat.Factory[T,Thatwithscala.collection.immutable.Iterable[_]]):org.apache.pekko.stream.scaladsl.Sink[T,scala.concurrent.Future[That]]"
}
+@apidoc[Sink.collection](Sink$) {
scala="#collection[T,That](implicitcbf:scala.collection.Factory[T,Thatwithscala.collection.immutable.Iterable[_]]):org.apache.pekko.stream.scaladsl.Sink[T,scala.concurrent.Future[That]]"
}
## Description
-Collect values emitted from the stream into an arbitrary collection `That`.
The resulting collection is available through a `Future[That]` or when the
stream completes. Note that the collection boundaries are those defined in the
`CanBuildFrom` associated with the chosen collection. See [The Architecture of
Scala 2.13's
Collections](https://docs.scala-lang.org/overviews/core/architecture-of-scala-213-collections.html)
for more info. The [`seq`](seq.html) operator is a shorthand for `Sink [...]
+Collect values emitted from the stream into an arbitrary collection `That`.
The resulting collection is available through a `Future[That]` or when the
stream completes. Note that the collection boundaries are those defined in the
`scala.collection.Factory` associated with the chosen collection. See [The
Architecture of Scala 2.13's
Collections](https://docs.scala-lang.org/overviews/core/architecture-of-scala-213-collections.html)
for more info. The [`seq`](seq.html) operator is a shortha [...]
## Example
diff --git
a/docs/src/main/paradox/stream/operators/Source-or-Flow/mapWithResource.md
b/docs/src/main/paradox/stream/operators/Source-or-Flow/mapWithResource.md
index 3801af67ff..ee45deb158 100644
--- a/docs/src/main/paradox/stream/operators/Source-or-Flow/mapWithResource.md
+++ b/docs/src/main/paradox/stream/operators/Source-or-Flow/mapWithResource.md
@@ -32,8 +32,8 @@ Early completion can be done with combination of the
@apidoc[Flow.takeWhile](Flo
See also @ref:[unfoldResource](../Source/unfoldResource.md),
@ref:[unfoldResourceAsync](../Source/unfoldResourceAsync.md).
-You can configure the default dispatcher for this Source by changing the
`org.apache.pekko.stream.materializer.blocking-io-dispatcher`
-or set it for a given Source by using ActorAttributes.
+You can configure the default dispatcher for this Flow by changing the
`pekko.stream.materializer.blocking-io-dispatcher`
+or set it for a given Flow by using ActorAttributes.
## Examples
diff --git a/docs/src/main/paradox/stream/operators/Source/actorRef.md
b/docs/src/main/paradox/stream/operators/Source/actorRef.md
index 13fcb58629..6c9b8d3a75 100644
--- a/docs/src/main/paradox/stream/operators/Source/actorRef.md
+++ b/docs/src/main/paradox/stream/operators/Source/actorRef.md
@@ -14,12 +14,14 @@ Materialize an `ActorRef`, sending messages to it will emit
them on the stream.
a buffer but since communication is one way, there is no back pressure.
Handling overflow is done by either dropping
elements or failing the stream; the strategy is chosen by the user.
-The stream can be completed successfully by sending the actor reference a
`org.apache.pekko.actor.Status.Success`.
-If the content is `org.apache.pekko.stream.CompletionStrategy.immediately` the
completion will be signaled immediately.
-Otherwise, if the content is
`org.apache.pekko.stream.CompletionStrategy.draining` (or anything else)
-already buffered elements will be sent out before signaling completion.
-Sending `org.apache.pekko.actor.PoisonPill` will signal completion immediately
but this behavior is deprecated and scheduled to be removed.
-Using `org.apache.pekko.actor.ActorSystem.stop` to stop the actor and complete
the stream is *not supported*.
+The stream can be completed successfully by sending the actor reference a
message that is matched by the
+`completionMatcher`. If the matcher returns
`org.apache.pekko.stream.CompletionStrategy.immediately` the completion
+will be signaled immediately. If it returns
`org.apache.pekko.stream.CompletionStrategy.draining`, already buffered
+elements will be sent out before signaling completion.
+The stream can be failed by sending a message that is matched by the
`failureMatcher`; the extracted `Throwable` is
+used to fail the stream.
+`org.apache.pekko.actor.PoisonPill` and `org.apache.pekko.actor.Kill` messages
are ignored (a warning is logged) and
+do not complete the stream. Using `org.apache.pekko.actor.ActorSystem.stop` to
stop the actor and complete the stream is *not supported*.
See also:
diff --git
a/docs/src/main/paradox/stream/operators/StreamConverters/fromOutputStream.md
b/docs/src/main/paradox/stream/operators/StreamConverters/fromOutputStream.md
index 5bcbcc9d7a..9f4a5d8072 100644
---
a/docs/src/main/paradox/stream/operators/StreamConverters/fromOutputStream.md
+++
b/docs/src/main/paradox/stream/operators/StreamConverters/fromOutputStream.md
@@ -12,11 +12,11 @@ Create a sink that wraps an `OutputStream`.
Creates a Sink which writes incoming @apidoc[util.ByteString]s to a
`java.io.OutputStream` created by the given function.
-Materializes a @java[`CompletionStage`]@scala[`Future`] of `IOResult` that
will be completed with the size of the file (in bytes) on completion,
+Materializes a @java[`CompletionStage`]@scala[`Future`] of `IOResult` that
will be completed with the number of bytes written on completion,
and a possible exception if IO operation was not completed successfully.
-You can configure the default dispatcher for this Source by changing the
`org.apache.pekko.stream.materializer.blocking-io-dispatcher` or
-set it for a given Source by using `org.apache.pekko.stream.ActorAttributes`.
+You can configure the default dispatcher for this Sink by changing the
`pekko.stream.materializer.blocking-io-dispatcher` or
+set it for a given Sink by using `org.apache.pekko.stream.ActorAttributes`.
If `autoFlush` is true the OutputStream will be flushed whenever a byte array
is written, defaults to false.
The `OutputStream` will be closed when the stream flowing into this `Sink` is
completed. The `Sink`
diff --git
a/docs/src/main/paradox/stream/operators/StreamConverters/javaCollectorParallelUnordered.md
b/docs/src/main/paradox/stream/operators/StreamConverters/javaCollectorParallelUnordered.md
index 54aa469944..a80e510908 100644
---
a/docs/src/main/paradox/stream/operators/StreamConverters/javaCollectorParallelUnordered.md
+++
b/docs/src/main/paradox/stream/operators/StreamConverters/javaCollectorParallelUnordered.md
@@ -1,6 +1,6 @@
# StreamConverters.javaCollectorParallelUnordered
-Create a sink which materializes into a @scala[`Future`]
@java[`CompletionStage`] which will be completed with a result of the Java 8
`Collector` transformation and reduction operations.
+Create a sink which materializes into a @scala[`Future`]
@java[`CompletionStage`] which will be completed with a result of the Java
`Collector` transformation and reduction operations.
@ref[Additional Sink and Source
converters](../index.md#additional-sink-and-source-converters)
@@ -11,4 +11,17 @@ Create a sink which materializes into a @scala[`Future`]
@java[`CompletionStage`
## Description
-TODO: We would welcome help on contributing descriptions and examples, see:
https://github.com/akka/akka/issues/25646
+`javaCollectorParallelUnordered` creates a @apidoc[Sink] that accepts a
factory for a Java
@javadoc[java.util.stream.Collector](java.util.stream.Collector)
+and processes incoming elements in parallel. The elements are distributed over
`parallelism` workers using a
+@ref:[Balance](../Balance.md), so there is no guarantee about which worker
receives which element, and the
+relative order of the elements is not preserved. Each worker runs
asynchronously and accumulates the elements it
+receives into its own mutable result container created by the `Collector`.
After the stream completes, the
+partial results are merged using the `Collector`'s combiner and transformed by
its finisher. The sink materializes
+into a @scala[`Future`]@java[`CompletionStage`] holding the final result.
+
+Because the order of the elements is not preserved, only use this with a
`Collector` whose result does not depend
+on the order in which elements are accumulated and combined. If `parallelism`
is 1 this behaves exactly like
+@ref:[javaCollector](javaCollector.md).
+
+Since a stream can be materialized multiple times, the function producing the
`Collector` must be able to handle
+multiple invocations.
diff --git a/docs/src/main/paradox/stream/stream-composition.md
b/docs/src/main/paradox/stream/stream-composition.md
index bf978dd70a..afd5ed3754 100644
--- a/docs/src/main/paradox/stream/stream-composition.md
+++ b/docs/src/main/paradox/stream/stream-composition.md
@@ -131,8 +131,8 @@ As a first example, let's look at a more complex layout:
The diagram shows a `RunnableGraph` (remember, if there are no unwired ports,
the graph is closed, and therefore
can be materialized) that encapsulates a non-trivial stream processing
network. It contains fan-in, fan-out operators,
-directed and non-directed cycles. The `runnable()` method of the `GraphDSL`
object allows the creation of a
-general, closed, and runnable graph. For example the network on the diagram
can be realized like this:
+directed and non-directed cycles. Passing a closed graph built with
`GraphDSL.create()` to `RunnableGraph.fromGraph()`
+allows the creation of a general, closed, and runnable graph. For example the
network on the diagram can be realized like this:
Scala
: @@snip
[CompositionDocSpec.scala](/docs/src/test/scala/docs/stream/CompositionDocSpec.scala)
{ #complex-graph }
@@ -186,7 +186,7 @@ Java
It is not possible to use it as a `Flow` yet, though (i.e. we cannot call
`.filter()` on it), but `Flow`
has a `fromGraph()` method that adds the DSL to a `FlowShape`. There are
similar methods on `Source`,
-`Sink` and `BidiShape`, so it is easy to get back to the simpler DSL if an
operator has the right shape.
+`Sink` and `BidiFlow`, so it is easy to get back to the simpler DSL if an
operator has the right shape.
For convenience, it is also possible to skip the partial graph creation, and
use one of the convenience creator methods.
To demonstrate this, we will create the following graph:
diff --git a/docs/src/main/paradox/stream/stream-cookbook.md
b/docs/src/main/paradox/stream/stream-cookbook.md
index c957cf22ad..f42b9ba64e 100644
--- a/docs/src/main/paradox/stream/stream-cookbook.md
+++ b/docs/src/main/paradox/stream/stream-cookbook.md
@@ -77,7 +77,7 @@ instead; e.g. `Source.unfold` or `Source.unfoldResource`.
all the nested elements inside the sequences separately.
The `mapConcat` operation can be used to implement a one-to-many
transformation of elements using a mapper function
-in the form of @scala[`In => Seq[Out]`] @java[`In -> List<Out>`]. In this case
we want to map a @scala[`Seq`] @java[`List`] of elements to the elements in the
+in the form of @scala[`In => IterableOnce[Out]`] @java[`In ->
java.lang.Iterable<Out>`]. In this case we want to map a @scala[`Seq`]
@java[`List`] of elements to the elements in the
collection itself, so we can call @scala[`mapConcat(identity)`]
@java[`mapConcat(l -> l)`].
Scala
diff --git a/docs/src/main/paradox/stream/stream-customize.md
b/docs/src/main/paradox/stream/stream-customize.md
index c9d7b55619..34d0aa5587 100644
--- a/docs/src/main/paradox/stream/stream-customize.md
+++ b/docs/src/main/paradox/stream/stream-customize.md
@@ -388,8 +388,7 @@ Java
### Integration with actors
-**This section is a stub and will be extended in the next release**
-**This is a @ref:[may change](../common/may-change.md) feature***
+**This is a @ref:[may change](../common/may-change.md) feature**
It is possible to acquire an ActorRef that can be addressed from the outside
of the operator, similarly how
@apidoc[stage.AsyncCallback] allows injecting asynchronous events into an
operator logic. This reference can be obtained
@@ -428,8 +427,6 @@ Java
### Using attributes to affect the behavior of an operator
-**This section is a stub and will be extended in the next release**
-
Operators can access the @apidoc[stream.Attributes] object created by the
materializer. This contains all the applied (inherited)
attributes applying to the operator, ordered from least specific (outermost)
towards the most specific (innermost)
attribute. It is the responsibility of the operator to decide how to reconcile
this inheritance chain to a final effective
@@ -515,11 +512,12 @@ operator to integrate it into your stream topology. This
works with all @scalado
ports that you connect with the graph DSL.
Advanced Scala users may wonder whether it is possible to write extension
methods that enrich `FlowOps` to
-allow nicer syntax. The short answer is that Scala 2 does not support this in
a fully generic fashion, the problem is
-that it is impossible to abstract over the kind of stream that is being
extended because `Source`, `Flow`
-and `SubFlow` differ in the number and kind of their type parameters. While it
would be possible to write
-an implicit class that enriches them generically, this class would require
explicit instantiation with all type
-parameters due to [SI-2712](https://github.com/scala/bug/issues/2712). For a
partial workaround that unifies
+allow nicer syntax. The short answer is that this is not possible in a fully
generic fashion, the problem is
+that it is hard to abstract over the kind of stream that is being extended
because `Source`, `Flow`
+and `SubFlow` differ in the number and kind of their type parameters. Partial
unification (the fix for
+[SI-2712](https://github.com/scala/bug/issues/2712)), which is always enabled
in Scala 2.13 and Scala 3, helps the
+compiler infer such type constructors, but it does not remove the need to
abstract over these differently shaped
+type constructors. For a partial workaround that unifies
extensions to `Source` and `Flow` see [this sketch by R.
Kuhn](https://gist.github.com/rkuhn/2870fcee4937dda2cad5).
A lot simpler is the task of adding an extension method to `Source` as shown
below:
@@ -537,6 +535,6 @@ shown in the linked sketch the author encountered such a
density of compiler Sta
that he gave up).
It is interesting to note that a simplified form of this problem has found its
way into the [dotty test
suite](https://github.com/lampepfl/dotty/pull/1186/files).
-Dotty is the development version of Scala on its way to Scala 3.
+Dotty was the development name of the compiler that became Scala 3.
@@@
diff --git a/docs/src/main/paradox/stream/stream-flows-and-basics.md
b/docs/src/main/paradox/stream/stream-flows-and-basics.md
index ef1c566240..940b85f5b7 100644
--- a/docs/src/main/paradox/stream/stream-flows-and-basics.md
+++ b/docs/src/main/paradox/stream/stream-flows-and-basics.md
@@ -115,11 +115,13 @@ both a `Source` and a `Sink` (in order to run a `Flow`,
since it has neither att
@@@ div { .group-java }
-After running (materializing) the
@javadoc[RunnableGraph](pekko.stream.javadsl.RunnableGraph) we get a special
container object, the `MaterializedMap`. Both
-sources and sinks are able to put specific objects into this map. Whether they
put something in or not is implementation
-dependent.
+After running (materializing) the `RunnableGraph<T>` we get back the
materialized value of type T. Every stream
+operator can produce a materialized value, and it is the responsibility of the
user to combine them to a new type.
+In the above example, we used `toMat` to indicate that we want to transform
the materialized value of the source and
+sink, and we used the convenience function `Keep.right()` to say that we are
only interested in the materialized value
+of the sink.
-For example, a
@javadoc[Sink.fold](pekko.stream.javadsl.Sink$#fold(java.lang.Object,org.apache.pekko.japi.function.Function2))
will make a @javadoc[CompletionStage](java.util.concurrent.CompletionStage)
available in this map which will represent the result
+In our example, the
@javadoc[Sink.fold](pekko.stream.javadsl.Sink$#fold(java.lang.Object,org.apache.pekko.japi.function.Function2))
materializes a value of type
@javadoc[CompletionStage](java.util.concurrent.CompletionStage) which will
represent the result
of the folding process over the stream. In general, a stream can expose
multiple materialized values,
but it is quite common to be interested in only the value of the Source or the
Sink in the stream. For this reason
there is a convenience method called `runWith()` available for
@javadoc[Sink](pekko.stream.javadsl.Sink),
@javadoc[Source](pekko.stream.javadsl.Source) or
@javadoc[Flow](pekko.stream.javadsl.Flow) requiring, respectively,
@@ -154,10 +156,10 @@ by providing named fan-out elements such as broadcast
(signals all down-stream e
In the above example we used the `runWith` method, which both materializes the
stream and returns the materialized value
of the given sink or source.
-Since a stream can be materialized multiple times, the @scala[materialized
value will also be calculated anew] @java[`MaterializedMap` returned is
different] for each such
+Since a stream can be materialized multiple times, the @scala[materialized
value will also be calculated anew] @java[materialized value will also be
calculated anew] for each such
materialization, usually leading to different values being returned each time.
In the example below, we create two running materialized instances of the
stream that we described in the `runnable`
-variable. Both materializations give us a different
@scala[@scaladoc[Future](scala.concurrent.Future)]@java[@javadoc[CompletionStage](java.util.concurrent.CompletionStage)]
from the map even though we used the same `sink`
+variable. Both materializations give us a different
@scala[@scaladoc[Future](scala.concurrent.Future)]@java[@javadoc[CompletionStage](java.util.concurrent.CompletionStage)]
even though we used the same `sink`
to refer to the future:
Scala
@@ -189,7 +191,7 @@ Java
In accordance to the Reactive Streams specification ([Rule
2.13](https://github.com/reactive-streams/reactive-streams-jvm#2.13))
Pekko Streams do not allow `null` to be passed through the stream as an
element. In case you want to model the concept
-of absence of a value we recommend using
@scala[@scaladoc[scala.Option](scala.Option) or
@scaladoc[scala.util.Either](scala.util.Either)]@java[@javadoc[java.util.Optional](java.util.Optional)
which is available since Java 8].
+of absence of a value we recommend using
@scala[@scaladoc[scala.Option](scala.Option) or
@scaladoc[scala.util.Either](scala.util.Either)]@java[@javadoc[java.util.Optional](java.util.Optional)].
## Back-pressure explained
@@ -315,7 +317,7 @@ operators that have been added since then.
@@@ warning
-Without fusing (i.e. up to version 2.0-M2) each stream operator had an
implicit input buffer
+Without fusing (as was the case in very early versions of the streams
implementation) each stream operator had an implicit input buffer
that holds a few elements for efficiency reasons. If your flow graphs contain
cycles then these buffers
may have been crucial in order to avoid deadlocks. With fusing these implicit
buffers are no longer
there, data elements are passed without buffering between fused operators. In
those cases where buffering
diff --git a/docs/src/main/paradox/stream/stream-quickstart.md
b/docs/src/main/paradox/stream/stream-quickstart.md
index bb9e19d276..6e78229ce3 100644
--- a/docs/src/main/paradox/stream/stream-quickstart.md
+++ b/docs/src/main/paradox/stream/stream-quickstart.md
@@ -311,12 +311,13 @@ Java
@@@ note
-The name `flatMap` was consciously avoided due to its proximity with
for-comprehensions and monadic composition.
+The name `flatMap` was originally avoided for this operator due to its
proximity with for-comprehensions and monadic composition.
It is problematic for two reasons: @scala[first]@java[firstly], flattening by
concatenation is often undesirable in bounded stream processing
due to the risk of deadlock (with merge being the preferred strategy), and
@scala[second]@java[secondly], the monad laws would not hold for
-our implementation of flatMap (due to the liveness issues).
+an implementation of flatMap on streams (due to the liveness issues).
+@scala[The Scala API does provide `flatMap`, but only as an alias for
@ref:[flatMapConcat](operators/Source-or-Flow/flatMapConcat.md) that was added
(as an API that may change) to enable for-comprehensions; it operates on
streams (the supplied function returns a `Source`), not on collections.]
-Please note that the @apidoc[mapConcat](stream.*.Source)
{scala="#mapConcat[T](f:Out=%3EIterableOnce[T]):FlowOps.this.Repr[T]"
java="#mapConcat(org.apache.pekko.japi.function.Function)"} requires the
supplied function to return @scala[an iterable (`f: Out =>
immutable.Iterable[T]`]@java[a strict collection (`Out f ->
java.util.List<T>`)],
+Please note that the @apidoc[mapConcat](stream.*.Source)
{scala="#mapConcat[T](f:Out=%3EIterableOnce[T]):FlowOps.this.Repr[T]"
java="#mapConcat(org.apache.pekko.japi.function.Function)"} requires the
supplied function to return @scala[an iterable (`f: Out =>
IterableOnce[T]`)]@java[an iterable (`Out f -> java.lang.Iterable<T>`)],
whereas `flatMap` would have to operate on streams all the way through.
@@@
diff --git a/docs/src/main/paradox/stream/stream-testkit.md
b/docs/src/main/paradox/stream/stream-testkit.md
index bd2dd2223a..2129b54d60 100644
--- a/docs/src/main/paradox/stream/stream-testkit.md
+++ b/docs/src/main/paradox/stream/stream-testkit.md
@@ -92,7 +92,7 @@ Java
: @@snip
[StreamTestKitDocTest.java](/docs/src/test/java/jdocs/stream/StreamTestKitDocTest.java)
{ #sink-actorref }
Similarly to `Sink.actorRef` that provides control over received
-elements, we can use @apidoc[Source.actorRef](stream.*.Source$)
{scala="#actorRef[T](completionMatcher:PartialFunction[Any,org.apache.pekko.stream.CompletionStrategy],failureMatcher:PartialFunction[Any,Throwable],bufferSize:Int,overflowStrategy:org.apache.pekko.stream.OverflowStrategy):org.apache.pekko.stream.scaladsl.Source[T,org.apache.pekko.actor.ActorRef]"
java="#actorRef(int,org.apache.pekko.stream.OverflowStrategy)"} and have full
control over
+elements, we can use @apidoc[Source.actorRef](stream.*.Source$)
{scala="#actorRef[T](completionMatcher:PartialFunction[Any,org.apache.pekko.stream.CompletionStrategy],failureMatcher:PartialFunction[Any,Throwable],bufferSize:Int,overflowStrategy:org.apache.pekko.stream.OverflowStrategy):org.apache.pekko.stream.scaladsl.Source[T,org.apache.pekko.actor.ActorRef]"
java="#actorRef(org.apache.pekko.japi.function.Function,org.apache.pekko.japi.function.Function,int,org.apache.pekko.stream.Overf
[...]
elements to be sent.
Scala
@@ -111,7 +111,7 @@ provide sources and sinks that materialize to probes that
allow fluent API.
### Using the TestKit
-A sink returned by @apidoc[TestSink.probe](stream.testkit.*.TestSink$)
{scala="#probe[T](implicitsystem:org.apache.pekko.actor.ActorSystem):org.apache.pekko.stream.scaladsl.Sink[T,org.apache.pekko.stream.testkit.TestSubscriber.Probe[T]]"
java="#probe(org.apache.pekko.actor.ActorSystem)"} allows manual control over
demand and
+A sink returned by
@scala[@scaladoc[TestSink()](pekko.stream.testkit.scaladsl.TestSink$#apply[T]()(implicitsystem:org.apache.pekko.actor.ClassicActorSystemProvider):org.apache.pekko.stream.scaladsl.Sink[T,org.apache.pekko.stream.testkit.TestSubscriber.Probe[T]])]@java[@javadoc[TestSink.create](pekko.stream.testkit.javadsl.TestSink#create(org.apache.pekko.actor.ClassicActorSystemProvider))]
allows manual control over demand and
assertions over elements coming downstream.
Scala
@@ -120,7 +120,7 @@ Scala
Java
: @@snip
[StreamTestKitDocTest.java](/docs/src/test/java/jdocs/stream/StreamTestKitDocTest.java)
{ #test-sink-probe }
-A source returned by @apidoc[TestSource.probe](stream.testkit.*.TestSource$)
{scala="#probe[T](implicitsystem:org.apache.pekko.actor.ActorSystem):org.apache.pekko.stream.scaladsl.Source[T,org.apache.pekko.stream.testkit.TestPublisher.Probe[T]]"
java="#probe(org.apache.pekko.actor.ActorSystem)"} can be used for asserting
demand or
+A source returned by
@scala[@scaladoc[TestSource()](pekko.stream.testkit.scaladsl.TestSource$#apply[T]()(implicitsystem:org.apache.pekko.actor.ClassicActorSystemProvider):org.apache.pekko.stream.scaladsl.Source[T,org.apache.pekko.stream.testkit.TestPublisher.Probe[T]])]@java[@javadoc[TestSource.create](pekko.stream.testkit.javadsl.TestSource#create(org.apache.pekko.actor.ClassicActorSystemProvider))]
can be used for asserting demand or
controlling when stream is completed or ended with an error.
Scala
diff --git a/docs/src/main/paradox/supervision-classic.md
b/docs/src/main/paradox/supervision-classic.md
index 224ef5a2eb..3b8c27f779 100644
--- a/docs/src/main/paradox/supervision-classic.md
+++ b/docs/src/main/paradox/supervision-classic.md
@@ -76,7 +76,7 @@ user-created actors, the guardian named `"/user"`. Actors
created using
`system.actorOf()` are children of this actor. This means that when this
guardian terminates, all normal actors in the system will be shutdown, too. It
also means that this guardian’s supervisor strategy determines how the
-top-level normal actors are supervised. Since Akka 2.1 it is possible to
+top-level normal actors are supervised. It is possible to
configure this using the setting `pekko.actor.guardian-supervisor-strategy`,
which takes the fully-qualified class-name of a
`SupervisorStrategyConfigurator`. When the guardian escalates a failure,
@@ -105,7 +105,7 @@ escalated … but to whom? Since every real actor has a
supervisor, the
supervisor of the root guardian cannot be a real actor. And because this means
that it is “outside of the bubble”, it is called the “bubble-walker”. This is a
synthetic `ActorRef` which in effect stops its child upon the first sign
-of trouble and sets the actor system’s `isTerminated` status to `true` as
+of trouble and completes the actor system’s
@scala[`whenTerminated`]@java[`getWhenTerminated`] future as
soon as the root guardian is fully terminated (all children recursively
stopped).
diff --git a/docs/src/main/paradox/testing.md b/docs/src/main/paradox/testing.md
index ec470368e4..62c01ded15 100644
--- a/docs/src/main/paradox/testing.md
+++ b/docs/src/main/paradox/testing.md
@@ -177,7 +177,7 @@ call is non-blocking (polling mode).
@@@
-* @scala[`receiveWhile[T](max: Duration, idle: Duration, messages: Int)(pf:
PartialFunction[Any, T]): Seq[T]`]@java[`public <T> List<T>
receiveWhile(Duration max, Duration idle, Int messages, Function<Object, T> f)`]
+* @scala[`receiveWhile[T](max: Duration, idle: Duration, messages: Int)(pf:
PartialFunction[Any, T]): Seq[T]`]@java[`public <T> List<T>
receiveWhile(Duration max, Duration idle, int messages, Function<Object, T> f)`]
Collect messages as long as
* they are matching the given partial function
* the given time interval is not used up
@@ -200,11 +200,10 @@ Poll the given assert function every `interval` until it
does not throw
an exception or the `max` duration is used up. If the timeout expires the
last exception is thrown. @scala[The interval defaults to 100 ms and the
maximum defaults
to the time remaining in the innermost enclosing @ref:[within](#testkit-within)
-block. The interval defaults to 100 ms and the maximum defaults to the time
-remaining in the innermost enclosing @ref:[within](#testkit-within) block.]
Return an arbitrary value that would be returned from awaitAssert if
successful, if not interested in such value you can return null.
+block.] Return an arbitrary value that would be returned from awaitAssert if
successful, if not interested in such value you can return null.
* @scala[`ignoreMsg(pf: PartialFunction[AnyRef, Boolean])`]@java[`public void
ignoreMsg(Function<Object, Boolean> f)`]
-@scala[`ignoreMsg`]@java[`public void ignoreMsg()`]
+@scala[`ignoreNoMsg()`]@java[`public void ignoreNoMsg()`]
@java[There are also cases where not all messages sent to the test kit are
actually
relevant to the test, but removing them would mean altering the actors under
test. For this purpose it is possible to ignore certain messages.]
@@ -813,7 +812,7 @@ to the @ref:[reference
configuration](general/configuration-reference.md#config-
Ray Roestenburg's example code from his blog, which unfortunately is only
available on
[web
archive](https://web.archive.org/web/20180114133958/http://roestenburg.agilesquad.com/2011/02/unit-testing-akka-actors-with-testkit_12.html),
-adapted to work with Akka 2.x.
+adapted to work with Pekko.
@@snip
[TestKitUsageSpec.scala](/docs/src/test/scala/docs/testkit/TestKitUsageSpec.scala)
{ #testkit-usage }
diff --git a/docs/src/main/paradox/typed/actors.md
b/docs/src/main/paradox/typed/actors.md
index 8552e7d78f..0d032a39aa 100644
--- a/docs/src/main/paradox/typed/actors.md
+++ b/docs/src/main/paradox/typed/actors.md
@@ -407,8 +407,8 @@ problematic, so passing an
@scala[`ActorRef[PublishSessionMessage]`]@java[`Actor
#### AbstractMatchingBehavior API
The `AbstractBehavior` API makes use of a builder on receipt of the first
message by the actor. The `Receive` built
-by this builder performs `instanceof` checks and casts "behind the scenes".
Pattern-matching features introduced in Java
-17 and refined in subsequent versions improve the ergonomics of expressing
this logic directly in code. Users of other
+by this builder performs `instanceof` checks and casts "behind the scenes".
Pattern matching for `instanceof`
+(Java 16+) and pattern matching for `switch` (Java 21+) improve the ergonomics
of expressing this logic directly in code. Users of other
JVM languages (such as Kotlin) may also prefer to not use a builder while
using the Java DSL (note that the Scala DSL's
`AbstractBehavior` does not make use of builders).
diff --git a/docs/src/main/paradox/typed/cluster-concepts.md
b/docs/src/main/paradox/typed/cluster-concepts.md
index ab044c0263..452ffad827 100644
--- a/docs/src/main/paradox/typed/cluster-concepts.md
+++ b/docs/src/main/paradox/typed/cluster-concepts.md
@@ -72,7 +72,7 @@ To be able to survive sudden abnormalities, such as garbage
collection pauses an
transient network failures the failure detector is easily
@ref:[configurable](cluster.md#using-the-failure-detector)
for tuning to your environments and needs.
-In a cluster each node is monitored by a few (default maximum 5) other nodes.
+In a cluster each node is monitored by a few (default maximum 9) other nodes.
The nodes to monitor are selected from neighbors in a hashed ordered node ring.
This is to increase the likelihood to monitor across racks and data centers,
but the order
is the same on all nodes, which ensures full coverage.
diff --git a/docs/src/main/paradox/typed/cluster.md
b/docs/src/main/paradox/typed/cluster.md
index 12e46a5964..f96cba41e0 100644
--- a/docs/src/main/paradox/typed/cluster.md
+++ b/docs/src/main/paradox/typed/cluster.md
@@ -295,7 +295,7 @@ Note that @ref:[Cluster Singleton](cluster-singleton.md) or
@ref:[Cluster Shardi
are running on a crashed (unreachable) node will not be started on another
node until the previous node has
been removed from the Cluster. Removal of crashed (unreachable) nodes is
performed after a downing decision.
-Downing can also be performed programmatically with
@scala[`Cluster(system).manager !
Down(address)`]@java[`Cluster.get(system).manager().tell(Down(address))`],
+Downing can also be performed programmatically with
@scala[`Cluster(system).manager !
Down(address)`]@java[`Cluster.get(system).manager().tell(new Down(address))`],
but that is mostly useful from tests and when implementing a
@apidoc[DowningProvider].
If a crashed node is restarted and joining the cluster again with the same
hostname and port, the previous incarnation
@@ -340,7 +340,7 @@ Cluster uses the
@apidoc[remote.PhiAccrualFailureDetector](PhiAccrualFailureDete
implementing the @apidoc[remote.FailureDetector](FailureDetector) and
configuring it:
```
-pekko.cluster.implementation-class = "com.example.CustomFailureDetector"
+pekko.cluster.failure-detector.implementation-class =
"com.example.CustomFailureDetector"
```
In the @ref:[Cluster Configuration](#configuration) you may want to adjust
these
diff --git a/docs/src/main/paradox/typed/dispatchers.md
b/docs/src/main/paradox/typed/dispatchers.md
index f1f11f975d..71798be5d1 100644
--- a/docs/src/main/paradox/typed/dispatchers.md
+++ b/docs/src/main/paradox/typed/dispatchers.md
@@ -102,7 +102,7 @@ There are 2 different types of message dispatchers:
* Use cases: Default dispatcher, Bulkheading
* Driven by: `java.util.concurrent.ExecutorService`.
Specify using "executor" using "fork-join-executor",
"thread-pool-executor" or the fully-qualified
- class name of an
`org.apache.pekko.dispatcher.ExecutorServiceConfigurator` implementation.
+ class name of an `org.apache.pekko.dispatch.ExecutorServiceConfigurator`
implementation.
* **PinnedDispatcher**
@@ -128,9 +128,9 @@ section and the `default-dispatcher` section of the
@ref:[configuration](../gene
The `parallelism-max` for the `fork-join-executor` does not set the upper
bound on the total number of threads
allocated by the ForkJoinPool. It is a setting specifically talking about the
number of *hot*
threads the pool will keep running in order to reduce the latency of handling
a new incoming task.
-You can read more about parallelism in the JDK's [ForkJoinPool
documentation](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ForkJoinPool.html).
+You can read more about parallelism in the JDK's [ForkJoinPool
documentation](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/ForkJoinPool.html).
-When Running on Java 9+, you can use `maximum-pool-size` to set the upper
bound on the total number of threads allocated by the ForkJoinPool.
+You can use `maximum-pool-size` to set the upper bound on the total number of
threads allocated by the ForkJoinPool.
When running on Java 25+, the `minimum-runnable` setting for the
`fork-join-executor` defaults to a JDK-aware value
(`min(8, max(1, parallelism / 2))`) instead of the historical `1`. This raises
the number of compensation threads the
@@ -161,7 +161,7 @@ default; use an explicit application or test configuration
when opting in.
@@@ note
The `thread-pool-executor` dispatcher is implemented using by a
`java.util.concurrent.ThreadPoolExecutor`.
-You can read more about it in the JDK's [ThreadPoolExecutor
documentation](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ThreadPoolExecutor.html).
+You can read more about it in the JDK's [ThreadPoolExecutor
documentation](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/ThreadPoolExecutor.html).
@@@
diff --git a/docs/src/main/paradox/typed/distributed-data.md
b/docs/src/main/paradox/typed/distributed-data.md
index 7816a1eb80..4eb7727b8e 100644
--- a/docs/src/main/paradox/typed/distributed-data.md
+++ b/docs/src/main/paradox/typed/distributed-data.md
@@ -185,8 +185,8 @@ sent for all matching keys, also new keys added later.
A data entry can be deleted by sending a `Replicator.Delete` message to the
local
`Replicator`. As reply of the `Delete` a `Replicator.DeleteSuccess` is sent to
the `replyTo` of the `Delete` if the value was successfully deleted according
to the supplied
-consistency level within the supplied timeout. Otherwise a
`Replicator.ReplicationDeleteFailure`
-is sent. Note that `ReplicationDeleteFailure` does not mean that the delete
completely failed or
+consistency level within the supplied timeout. Otherwise a
`Replicator.DeleteFailure`
+is sent. Note that `DeleteFailure` does not mean that the delete completely
failed or
was rolled back. It may still have been replicated to some nodes, and may
eventually be replicated
to all nodes.
@@ -313,7 +313,7 @@ the `Update` when the `GetSuccess`, `GetFailure` or
`NotFound` reply is received
needed when you need to base a decision on latest information or when removing
entries from an `ORSet`
or `ORMap`. If an entry is added to an `ORSet` or `ORMap` from one node and
removed from another
node the entry will only be removed if the added entry is visible on the node
where the removal is
-performed (hence the name observed-removed set).
+performed (hence the name observed-remove set).
@@@ warning
@@ -729,7 +729,7 @@ data is typically replicated to other nodes immediately
according to the given `
pekko.cluster.distributed-data.durable.lmdb.write-behind-interval = 200 ms
```
-Note that you should be prepared to receive `WriteFailure` as reply to an
`Update` of a
+Note that you should be prepared to receive `StoreFailure` as reply to an
`Update` of a
durable entry if the data could not be stored for some reason. When enabling
`write-behind-interval`
such errors will only be logged and `UpdateSuccess` will still be the reply to
the `Update`.
diff --git a/docs/src/main/paradox/typed/durable-state/persistence.md
b/docs/src/main/paradox/typed/durable-state/persistence.md
index 5365c43ca3..d882d716d1 100644
--- a/docs/src/main/paradox/typed/durable-state/persistence.md
+++ b/docs/src/main/paradox/typed/durable-state/persistence.md
@@ -307,7 +307,7 @@ There is also an example illustrating an @ref:[optional
initial state](persisten
The @ref:[Request-Response interaction
pattern](../interaction-patterns.md#request-response) is very common for
persistent actors, because you typically want to know if the command was
rejected due to validation errors and
-when accepted you want a confirmation when the events have been successfully
stored.
+when accepted you want a confirmation when the state has been successfully
stored.
Therefore you typically include a
@scala[`ActorRef[ReplyMessageType]`]@java[`ActorRef<ReplyMessageType>`]. If the
command can either have a successful response or a validation error returned,
the generic response type @scala[`StatusReply[ReplyType]`]
@@ -315,7 +315,7 @@ command can either have a successful response or a
validation error returned, th
a pre defined @scala[`StatusReply.Ack`]@java[`StatusReply.ack()`] of type
@scala[`StatusReply[Done]`]@java[`StatusReply<Done>`]
can be used.
-After validation errors or after persisting events, using a `thenRun` side
effect, the reply message can
+After validation errors or after persisting the state, using a `thenRun` side
effect, the reply message can
be sent to the `ActorRef`.
Scala
@@ -357,7 +357,7 @@ The `ReplyEffect` is created with
@scala[`Effect.reply`]@java[`Effect().reply`],
@scala[`Effect.thenReply`]@java[`Effect().thenReply`], or
@scala[`Effect.thenNoReply`]@java[`Effect().thenNoReply`].
@java[Note that command handlers are defined with
`newCommandHandlerWithReplyBuilder` when using
-`EventSourcedBehaviorWithEnforcedReplies`, as opposed to
newCommandHandlerBuilder when using `EventSourcedBehavior`.]
+`DurableStateBehaviorWithEnforcedReplies`, as opposed to
newCommandHandlerBuilder when using `DurableStateBehavior`.]
Scala
: @@snip
[AccountExampleWithCommandHandlersInDurableState.scala](/cluster-sharding-typed/src/test/scala/docs/org/apache/pekko/cluster/sharding/typed/AccountExampleWithCommandHandlersInDurableState.scala)
{ #reply }
diff --git a/docs/src/main/paradox/typed/from-classic.md
b/docs/src/main/paradox/typed/from-classic.md
index b64dbec57a..f8c601af94 100644
--- a/docs/src/main/paradox/typed/from-classic.md
+++ b/docs/src/main/paradox/typed/from-classic.md
@@ -110,7 +110,7 @@ A classic actor is started with the `actorOf` method of the
`ActorContext` or `A
Corresponding method in Typed is called `spawn` in the
@scala[`org.apache.pekko.actor.typed.scaladsl.ActorContext`]@java[`org.apache.pekko.actor.typed.javadsl.ActorContext`].
-There is no `spawn` method in the
@scala[`org.apache.pekko.actor.typed.scaladsl.ActorSystem`]@java[`org.apache.pekko.actor.typed.javadsl.ActorSystem`]
+There is no `spawn` method in the `org.apache.pekko.actor.typed.ActorSystem`
for creating top level actors. Instead, there is a single top level actor
defined by a user guardian `Behavior` that is given
when starting the `ActorSystem`. Other actors are started as children of that
user guardian actor or
children of other actors in the actor hierarchy. This is explained more in
@ref:[ActorSystem](#actorsystem).
diff --git a/docs/src/main/paradox/typed/guide/modules.md
b/docs/src/main/paradox/typed/guide/modules.md
index dcfab82031..bb997bcc92 100644
--- a/docs/src/main/paradox/typed/guide/modules.md
+++ b/docs/src/main/paradox/typed/guide/modules.md
@@ -129,7 +129,7 @@ Challenges that Sharding solves include the following:
symbol1=PekkoVersion
value1="$pekko.version$"
group=org.apache.pekko
- artifact=pekko-cluster-singleton_$scala.binary.version$
+ artifact=pekko-cluster-typed_$scala.binary.version$
version=PekkoVersion
}
@@ -173,14 +173,8 @@ Persistence tackles the following challenges:
### Projections
-@@dependency[sbt,Maven,Gradle] {
- bomGroup=org.apache.pekko bomArtifact=pekko-bom_$scala.binary.version$
bomVersionSymbols=PekkoVersion
- symbol1=PekkoVersion
- value1="$pekko.version$"
- group=org.apache.pekko
- artifact=pekko-projection-core_$scala.binary.version$
- version=PekkoVersion
-}
+[Pekko Projections]($pekko.doc.dns$/docs/pekko-projection/current/) is a
separate module from Pekko, with its own
+release cycle and version. See its documentation for the
`pekko-projection-core` dependency and the version to use.
Projections provides a simple API for consuming a stream of events for
projection into a variety of downstream options. The core dependency provides
only the API and other provider dependencies are required for different source
and sink implementations.
diff --git a/docs/src/main/paradox/typed/guide/tutorial_1.md
b/docs/src/main/paradox/typed/guide/tutorial_1.md
index 3875974db5..ea9a1c7127 100644
--- a/docs/src/main/paradox/typed/guide/tutorial_1.md
+++ b/docs/src/main/paradox/typed/guide/tutorial_1.md
@@ -43,7 +43,7 @@ Scala
Java
: @@snip
[ActorHierarchyExperiments.java](/docs/src/test/java/jdocs/typed/tutorial_1/ActorHierarchyExperiments.java)
{ #print-refs }
-Note the way a message asked the first actor to do its work. We sent the
message by using the parent's reference: @scala[`firstRef !
"printit"`]@java[`firstRef.tell("printit", ActorRef.noSender())`]. When the
code executes, the output includes the references for the first actor and the
child it created as part of the `printit` case. Your output should look similar
to the following:
+Note the way a message asked the first actor to do its work. We sent the
message by using the parent's reference: @scala[`firstRef !
"printit"`]@java[`firstRef.tell("printit")`]. When the code executes, the
output includes the references for the first actor and the child it created as
part of the `printit` case. Your output should look similar to the following:
```
First: Actor[pekko://testSystem/user/first-actor#1053618476]
diff --git a/docs/src/main/paradox/typed/interaction-patterns.md
b/docs/src/main/paradox/typed/interaction-patterns.md
index a03349cf31..d117f4ee46 100644
--- a/docs/src/main/paradox/typed/interaction-patterns.md
+++ b/docs/src/main/paradox/typed/interaction-patterns.md
@@ -247,12 +247,12 @@ Having to define two response classes and a shared
supertype for every request t
where you also have to make sure the messages can be serialized to be sent
over the network.
To help with this a generic status-response type is included in Pekko:
@apidoc[StatusReply], everywhere where `ask` can be used
-there is also a second method @apidoc[askWithStatus](typed.*.ActorFlow$)
{scala="#askWithStatus[I,Q,A](parallelism:Int)(ref:org.apache.pekko.actor.typed.ActorRef[Q])(makeMessage:(I,org.apache.pekko.actor.typed.ActorRef[org.apache.pekko.pattern.StatusReply[A]])=%3EQ)(implicittimeout:org.apache.pekko.util.Timeout):org.apache.pekko.stream.scaladsl.Flow[I,A,org.apache.pekko.NotUsed]"
java="#askWithStatus(int,org.apache.pekko.actor.typed.ActorRef,java.time.Duration,java.util.function.BiFuncti
[...]
+there is also a second method @apidoc[askWithStatus](typed.*.ActorContext)
{scala="#askWithStatus[Req,Res](target:org.apache.pekko.actor.typed.RecipientRef[Req],createRequest:org.apache.pekko.actor.typed.ActorRef[org.apache.pekko.pattern.StatusReply[Res]]=%3EReq)(mapResponse:scala.util.Try[Res]=%3ET)(implicitresponseTimeout:org.apache.pekko.util.Timeout,implicitclassTag:scala.reflect.ClassTag[Res]):Unit"
java="#askWithStatus(java.lang.Class,org.apache.pekko.actor.typed.RecipientRef,java.
[...]
and help with handling validation errors. Pekko includes pre-built serializers
for the type, so in the normal use case a clustered
application only needs to provide a serializer for the successful result.
For the case where the successful reply does not contain an actual value but
is more of an acknowledgment there is a pre defined
-@scala[@scaladoc[StatusReply.Ack](pekko.pattern.StatusReply$#Ack:org.apache.pekko.pattern.StatusReply[org.apache.pekko.Done])]@java[@javadoc[StatusReply.ack()](pekko.pattern.StatusReply$#ack())]
of type @scala[`StatusReply[Done]`]@java[`StatusReply<Done>`].
+@scala[@scaladoc[StatusReply.Ack](pekko.pattern.StatusReply$#Ack:org.apache.pekko.pattern.StatusReply[org.apache.pekko.Done])]@java[@javadoc[StatusReply.ack()](pekko.pattern.StatusReply#ack())]
of type @scala[`StatusReply[Done]`]@java[`StatusReply<Done>`].
Errors are preferably sent as a text describing what is wrong, but using
exceptions to attach a type is also possible.
@@ -494,8 +494,8 @@ This can be used with any type of
@apidoc[actor.typed.Behavior], including @apid
Scheduling of recurring messages can have two different characteristics:
* fixed-delay - The delay between sending subsequent messages will always be
(at least) the given `delay`.
- Use @apidoc[startTimerWithFixedDelay](actor.TimerScheduler)
{scala="#startTimerWithFixedDelay(key:Any,msg:Any,initialDelay:scala.concurrent.duration.FiniteDuration,delay:scala.concurrent.duration.FiniteDuration):Unit"
java="#startTimerWithFixedDelay(java.lang.Object,java.lang.Object,java.time.Duration,java.time.Duration)"}.
-* fixed-rate - The frequency of execution over time will meet the given
`interval`. Use @apidoc[startTimerAtFixedRate](actor.TimerScheduler)
{scala="#startTimerAtFixedRate(key:Any,msg:Any,interval:scala.concurrent.duration.FiniteDuration):Unit"
java="#startTimerAtFixedRate(java.lang.Object,java.lang.Object,java.time.Duration,java.time.Duration)"}.
+ Use @apidoc[startTimerWithFixedDelay](typed.*.TimerScheduler)
{scala="#startTimerWithFixedDelay(key:Any,msg:T,initialDelay:scala.concurrent.duration.FiniteDuration,delay:scala.concurrent.duration.FiniteDuration):Unit"
java="#startTimerWithFixedDelay(java.lang.Object,T,java.time.Duration,java.time.Duration)"}.
+* fixed-rate - The frequency of execution over time will meet the given
`interval`. Use @apidoc[startTimerAtFixedRate](typed.*.TimerScheduler)
{scala="#startTimerAtFixedRate(key:Any,msg:T,interval:scala.concurrent.duration.FiniteDuration):Unit"
java="#startTimerAtFixedRate(java.lang.Object,T,java.time.Duration)"}.
If you are uncertain of which one to use you should pick
`startTimerWithFixedDelay`.
@@ -509,12 +509,12 @@ it is appropriate for activities where it is more
important to keep the frequenc
than in the long run.
When using **fixed-rate** it will compensate the delay for a subsequent task
if the previous messages were delayed
-too long. In such cases, the actual sending interval will differ from the
interval passed to the `scheduleAtFixedRate`
+too long. In such cases, the actual sending interval will differ from the
interval passed to the `startTimerAtFixedRate`
method.
If the tasks are delayed longer than the `interval`, the subsequent message
will be sent immediately after the
prior one. This also has the consequence that after long garbage collection
pauses or other reasons when the JVM
-was suspended all "missed" tasks will execute when the process wakes up again.
For example, `scheduleAtFixedRate`
+was suspended all "missed" tasks will execute when the process wakes up again.
For example, `startTimerAtFixedRate`
with an interval of 1 second and the process is suspended for 30 seconds will
result in 30 messages being sent
in rapid succession to catch up. In the long run, the frequency of execution
will be exactly the reciprocal of
the specified `interval`.
@@ -525,8 +525,8 @@ timer that ticks once every second for ten seconds.
@@@ warning
-`scheduleAtFixedRate` can result in bursts of scheduled messages after long
garbage collection pauses,
-which may in worst case cause undesired load on the system.
`scheduleWithFixedDelay` is often preferred.
+`startTimerAtFixedRate` can result in bursts of scheduled messages after long
garbage collection pauses,
+which may in worst case cause undesired load on the system.
`startTimerWithFixedDelay` is often preferred.
@@@
diff --git a/docs/src/main/paradox/typed/mailboxes.md
b/docs/src/main/paradox/typed/mailboxes.md
index 2b3f9fcfe7..5a978e5c49 100644
--- a/docs/src/main/paradox/typed/mailboxes.md
+++ b/docs/src/main/paradox/typed/mailboxes.md
@@ -41,7 +41,7 @@ Scala
Java
: @@snip
[MailboxDocTest.java](/actor-typed-tests/src/test/java/jdocs/org/apache/pekko/typed/MailboxDocTest.java)
{ #select-mailbox }
-@apidoc[fromConfig](MailboxSelector$)
{scala="#fromConfig(path:String):org.apache.pekko.actor.typed.MailboxSelector"
java="#fromConfig(java.lang.String)"} takes an absolute config path to a block
defining the dispatcher in the config file:
+@apidoc[fromConfig](MailboxSelector$)
{scala="#fromConfig(path:String):org.apache.pekko.actor.typed.MailboxSelector"
java="#fromConfig(java.lang.String)"} takes an absolute config path to a block
defining the mailbox in the config file:
@@snip
[MailboxDocSpec.scala](/actor-typed-tests/src/test/resources/mailbox-config-sample.conf)
{ }
@@ -52,7 +52,7 @@ The default mailbox is used when the mailbox is not specified
and is the @apidoc
### Which Configuration is passed to the Mailbox Type
Each mailbox type is implemented by a class which extends
@apidoc[MailboxType](MailboxType)
-and takes two constructor arguments: a
@apidoc[ActorSystem.Settings](typed.Settings) object and
+and takes two constructor arguments: a
@apidoc[actor.ActorSystem.Settings](actor.ActorSystem.Settings) object and
a
[Config](https://lightbend.github.io/config/latest/api/index.html?com/typesafe/config/Config.html)
section. The latter is computed by obtaining the named
configuration section from the @apidoc[ActorSystem](typed.ActorSystem)
configuration, overriding its
`id` key with the configuration path of the mailbox type and adding a
diff --git a/docs/src/main/paradox/typed/persistence.md
b/docs/src/main/paradox/typed/persistence.md
index 3f47e8285e..a6ab6a046c 100644
--- a/docs/src/main/paradox/typed/persistence.md
+++ b/docs/src/main/paradox/typed/persistence.md
@@ -637,7 +637,9 @@ Java
: @@snip
[StashingExample.java](/persistence-typed/src/test/java/jdocs/org/apache/pekko/persistence/typed/StashingExample.java)
{ #stashing }
You should be careful to not send more messages to a persistent actor than it
can keep up with, otherwise the stash
-buffer will fill up and when reaching its maximum capacity the commands will
be dropped. The capacity can be configured with:
+buffer will fill up and when reaching its maximum capacity the commands will
be dropped (with the default
+`pekko.persistence.typed.stash-overflow-strategy = "drop"`; set it to `"fail"`
to fail the actor instead).
+The capacity (default 4096) can be configured with, for example:
```
pekko.persistence.typed.stash-capacity = 10000
diff --git a/docs/src/main/paradox/typed/reliable-delivery.md
b/docs/src/main/paradox/typed/reliable-delivery.md
index a1682f0df3..30c722b909 100644
--- a/docs/src/main/paradox/typed/reliable-delivery.md
+++ b/docs/src/main/paradox/typed/reliable-delivery.md
@@ -147,8 +147,8 @@ corresponding producer is started again. Even if the same
`ConsumerController` i
delivery of messages that had already been processed but the fact that they
were confirmed had not been stored yet.
This means that we have at-least-once delivery.
-If the consumer crashes, a new `ConsumerController` can be connected to the
original `ProducerConsumer`
-without restarting it. The `ProducerConsumer` will then redeliver all
unconfirmed messages. In that case
+If the consumer crashes, a new `ConsumerController` can be connected to the
original `ProducerController`
+without restarting it. The `ProducerController` will then redeliver all
unconfirmed messages. In that case
the unconfirmed messages will be delivered to the new consumer and some of
these may already have been
processed by the previous consumer.
Again, this means that we have at-least-once delivery.
diff --git a/docs/src/main/paradox/typed/replicated-eventsourcing-auction.md
b/docs/src/main/paradox/typed/replicated-eventsourcing-auction.md
index dee5254558..74ea6ea190 100644
--- a/docs/src/main/paradox/typed/replicated-eventsourcing-auction.md
+++ b/docs/src/main/paradox/typed/replicated-eventsourcing-auction.md
@@ -25,7 +25,7 @@ Scala
Java
: @@snip
[AuctionExample](/persistence-typed-tests/src/test/java/jdocs/org/apache/pekko/persistence/typed/ReplicatedAuctionExampleTest.java)
{ #events }
-The winner does not have to pay the highest bid but only enough to beat the
second highest, so the `highestCounterOffer` is in the `AuctionFinished` event.
+The winner does not have to pay the highest bid but only enough to beat the
second highest, so the `highestCounterOffer` is in the `WinnerDecided` event.
Let's have a look at the auction entity that will handle incoming commands:
@@ -36,7 +36,7 @@ Java
: @@snip
[AuctionExample](/persistence-typed-tests/src/test/java/jdocs/org/apache/pekko/persistence/typed/ReplicatedAuctionExampleTest.java)
{ #command-handler }
There is nothing specific to Replicated Event Sourcing about the command
handler. It is the same as a command handler for a standard
`EventSourcedBehavior`.
-For `OfferBid` and `AuctionFinished` we do nothing more than to emit
+For `OfferBid` and `Finish` we do nothing more than to emit
events corresponding to the command. For `GetHighestBid` we respond with
details from the state. Note, that we overwrite the actual
offer of the highest bid here with the amount of the `highestCounterOffer`.
This is done to follow the popular auction style where
the actual highest bid is never publicly revealed.
diff --git a/docs/src/main/paradox/typed/routers.md
b/docs/src/main/paradox/typed/routers.md
index 3d0f4be4b6..72b7fa6ff4 100644
--- a/docs/src/main/paradox/typed/routers.md
+++ b/docs/src/main/paradox/typed/routers.md
@@ -117,7 +117,7 @@ of routees stays relatively stable, but may be unfair if
the set of routees chan
This is the default for pool routers as the pool of routees is expected to
remain the same.
-An optional parameter `preferLocalRoutees` can be used for this strategy.
Routers will only use routees located in local actor system if
`preferLocalRoutees` is true and local routees do exist. The default value for
this parameter is false.
+For group routers, an optional parameter `preferLocalRoutees` can be used for
this strategy (it is not available for pool routers). Group routers will only
use routees located in local actor system if `preferLocalRoutees` is true and
local routees do exist. The default value for this parameter is false.
### Random
@@ -125,7 +125,7 @@ Randomly selects a routee when a message is sent through
the router.
This is the default for group routers as the group of routees is expected to
change as nodes join and leave the cluster.
-An optional parameter `preferLocalRoutees` can be used for this strategy.
Routers will only use routees located in local actor system if
`preferLocalRoutees` is true and local routees do exist. The default value for
this parameter is false.
+For group routers, an optional parameter `preferLocalRoutees` can be used for
this strategy (it is not available for pool routers). Group routers will only
use routees located in local actor system if `preferLocalRoutees` is true and
local routees do exist. The default value for this parameter is false.
### Consistent Hashing
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
