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 49d28aeed1 Repair API links in actor, IO and stream documentation
(#3654)
49d28aeed1 is described below
commit 49d28aeed18de32799292c5ad0aa37b69bd9342a
Author: He-Pin(kerr) <[email protected]>
AuthorDate: Fri Oct 23 17:26:30 2026 +0800
Repair API links in actor, IO and stream documentation (#3654)
* Repair API links in actor, IO and stream documentation
Motivation:
Several API references select the wrong language or point to renamed or
nested types incorrectly.
Modification:
Adapt the four related upstream link fixes to current Pekko names,
including Tcp.WritePath and TcpMessage.writePath, and provide matching
Scala/Java references.
Result:
Generated documentation points readers at the appropriate current API
entries.
Tests:
- Tests: Not run - docs only.
- Passed: `docs/paradox`.
- Passed: `+headerCheckAll`.
- Full `validatePullRequest` is left to remote CI.
References:
- Refs [akka/akka-core#32133](https://github.com/akka/akka-core/pull/32133).
- Refs [akka/akka-core#32147](https://github.com/akka/akka-core/pull/32147).
- Refs [akka/akka-core#32166](https://github.com/akka/akka-core/pull/32166).
- Refs [akka/akka-core#32170](https://github.com/akka/akka-core/pull/32170).
- Upstream commit:
[18336615e86e5a9a41a9bd89ee1b898f17a9a173](https://github.com/akka/akka-core/commit/18336615e86e5a9a41a9bd89ee1b898f17a9a173).
- Upstream commit:
[5405b2757ef41f087a5088264868d91c13bfe702](https://github.com/akka/akka-core/commit/5405b2757ef41f087a5088264868d91c13bfe702).
- Upstream commit:
[3d24594514b80cdc1b944a2f98cf0e7dad29bbc6](https://github.com/akka/akka-core/commit/3d24594514b80cdc1b944a2f98cf0e7dad29bbc6).
- Upstream commit:
[dd381c1803d0a3cb171ae8fecebfacffce1dd424](https://github.com/akka/akka-core/commit/dd381c1803d0a3cb171ae8fecebfacffce1dd424).
- Source snapshot: Akka `v2.9.0`
(`bf20e967571574994ccb3cae411401f5a9021ab9`). Its
[license](https://github.com/akka/akka-core/blob/v2.9.0/LICENSE) names
2026-10-23 as the Change Date and Apache License 2.0 as the Change License.
`LICENSE` and `NOTICE` record the source, and original copyright notices are
retained. Headers were generated/checked with the project sbt tasks.
* Keep licensing metadata outside the migration change
Motivation:
Keep PR #3654 scoped to its code or documentation change.
Modification:
Restore the root LICENSE and NOTICE files to main.
Result:
The migration diff retains its source headers without repository-level
licensing edits.
Tests:
- git diff --check passed.
- Verified every other file is unchanged; prior focused validation still
applies.
References:
Refs #3654.
* Complete TCP API links after review
Motivation:
Some TCP message references remained plain text while other mentions linked
to the corresponding Scala and Java API documentation.
Modification:
Link the remaining language-specific references and CompoundWrite mentions
using the existing API targets and method anchors.
Result:
Repeated TCP references consistently provide links in both language views.
Tests:
- Not run - docs only.
- sbt headerCreateAll docs/paradox +headerCheckAll: passed.
- 20 API page/fragment checks and generated Scala/Java links: passed.
- git diff --check: passed.
- Independent review and Qoder stdout review: No must-fix findings.
References:
Refs #3654
---
docs/src/main/paradox/io-tcp.md | 120 ++++++++++++++++++-------------------
docs/src/main/paradox/io-udp.md | 24 ++++----
docs/src/main/paradox/typed/fsm.md | 10 ++--
3 files changed, 77 insertions(+), 77 deletions(-)
diff --git a/docs/src/main/paradox/io-tcp.md b/docs/src/main/paradox/io-tcp.md
index e979429a4c..250ff9165e 100644
--- a/docs/src/main/paradox/io-tcp.md
+++ b/docs/src/main/paradox/io-tcp.md
@@ -27,7 +27,7 @@ Java
: @@snip [IODocTest.java](/docs/src/test/java/jdocs/io/japi/IODocTest.java) {
#imports }
All of the Pekko I/O APIs are accessed through manager objects. When using an
I/O API, the first step is to acquire a
-reference to the appropriate manager. The code below shows how to acquire a
reference to the `Tcp` manager.
+reference to the appropriate manager. The code below shows how to acquire a
reference to the @apidoc[org.apache.pekko.io.Tcp$] manager.
Scala
: @@snip [IODocSpec.scala](/docs/src/test/scala/docs/io/IODocSpec.scala) {
#manager }
@@ -47,8 +47,8 @@ Java
: @@snip [IODocTest.java](/docs/src/test/java/jdocs/io/japi/IODocTest.java) {
#client }
The first step of connecting to a remote address is sending a
-@scala[`Connect` message]@java[message by the `TcpMessage.connect` method] to
the TCP manager; in addition to the simplest form shown above there
-is also the possibility to specify a local `InetSocketAddress` to bind
+@scala[@scaladoc[Connect](org.apache.pekko.io.Tcp.Connect)
message]@java[message by the
@javadoc[TcpMessage.connect](org.apache.pekko.io.TcpMessage#connect(java.net.InetSocketAddress))
method] to the TCP manager; in addition to the simplest form shown above there
+is also the possibility to specify a local
@javadoc[InetSocketAddress](java.net.InetSocketAddress) to bind
to and a list of socket options to apply.
@@@ note
@@ -57,20 +57,20 @@ The SO_NODELAY (TCP_NODELAY on Windows) socket option
defaults to true in
Pekko, independently of the OS default settings. This setting disables Nagle's
algorithm, considerably improving latency for most applications. This setting
could be overridden by passing `SO.TcpNoDelay(false)` in the list of socket
-options of the @scala[`Connect` message]@java[message by the
`TcpMessage.connect` method].
+options of the @scala[@scaladoc[Connect](org.apache.pekko.io.Tcp.Connect)
message]@java[message by the
@javadoc[TcpMessage.connect](org.apache.pekko.io.TcpMessage#connect(java.net.InetSocketAddress))
method].
@@@
-The TCP manager will then reply either with a `CommandFailed` or it will
+The TCP manager will then reply either with a
@apidoc[org.apache.pekko.io.Tcp.CommandFailed] or it will
spawn an internal actor representing the new connection. This new actor will
-then send a `Connected` message to the original sender of the
-@scala[`Connect` message]@java[message by the `TcpMessage.connect` method].
+then send a @apidoc[org.apache.pekko.io.Tcp.Connected] message to the original
sender of the
+@scala[@scaladoc[Connect](org.apache.pekko.io.Tcp.Connect)
message]@java[message by the
@javadoc[TcpMessage.connect](org.apache.pekko.io.TcpMessage#connect(java.net.InetSocketAddress))
method].
-In order to activate the new connection a @scala[`Register`
message]@java[message by the `TcpMessage.register` method] must be
+In order to activate the new connection a
@scala[@scaladoc[Register](org.apache.pekko.io.Tcp.Register)
message]@java[message by the
@javadoc[TcpMessage.register](org.apache.pekko.io.TcpMessage#register(org.apache.pekko.actor.ActorRef))
method] must be
sent to the connection actor, informing that one about who shall receive data
from the socket. Before this step is done the connection cannot be used, and
there is an internal timeout after which the connection actor will shut itself
-down if no @scala[`Register` message]@java[message by the
`TcpMessage.register` method] is received.
+down if no @scala[@scaladoc[Register](org.apache.pekko.io.Tcp.Register)
message]@java[message by the
@javadoc[TcpMessage.register](org.apache.pekko.io.TcpMessage#register(org.apache.pekko.actor.ActorRef))
method] is received.
The connection actor watches the registered handler and closes the connection
when that one terminates, thereby cleaning up all internal resources associated
@@ -79,7 +79,7 @@ with that connection.
The actor in the example above uses `become` to switch from unconnected
to connected operation, demonstrating the commands and events which are
observed in that state. For a discussion on `CommandFailed` see
-[Throttling Reads and Writes](#throttling-reads-and-writes) below.
`ConnectionClosed` is a trait,
+[Throttling Reads and Writes](#throttling-reads-and-writes) below.
@apidoc[org.apache.pekko.io.Tcp.ConnectionClosed] is a trait,
which marks the different connection close events. The last line handles all
connection close events in the same way. It is possible to listen for more
fine-grained connection close events, see @ref:[Closing
Connections](#closing-connections) below.
@@ -92,12 +92,12 @@ Scala
Java
: @@snip [IODocTest.java](/docs/src/test/java/jdocs/io/japi/IODocTest.java) {
#server }
-To create a TCP server and listen for inbound connections, a @scala[`Bind`
command]@java[message by the `TcpMessage.bind` method]
+To create a TCP server and listen for inbound connections, a
@scala[@scaladoc[Bind](org.apache.pekko.io.Tcp.Bind) command]@java[message by
the
@javadoc[TcpMessage.bind](org.apache.pekko.io.TcpMessage#bind(org.apache.pekko.actor.ActorRef,java.net.InetSocketAddress,int))
method]
has to be sent to the TCP manager. This will instruct the TCP manager
-to listen for TCP connections on a particular `InetSocketAddress`; the
+to listen for TCP connections on a particular
@javadoc[InetSocketAddress](java.net.InetSocketAddress); the
port may be specified as `0` in order to bind to a random port.
-The actor sending the @scala[`Bind` message]@java[message by the
`TcpMessage.bind` method] will receive a `Bound`
+The actor sending the @scala[@scaladoc[Bind](org.apache.pekko.io.Tcp.Bind)
message]@java[message by the
@javadoc[TcpMessage.bind](org.apache.pekko.io.TcpMessage#bind(org.apache.pekko.actor.ActorRef,java.net.InetSocketAddress,int))
method] will receive a @apidoc[org.apache.pekko.io.Tcp.Bound]
message signaling that the server is ready to accept incoming connections;
this message also contains the `InetSocketAddress` to which the socket
was actually bound (i.e. resolved IP address and correct port number).
@@ -105,7 +105,7 @@ was actually bound (i.e. resolved IP address and correct
port number).
From this point forward the process of handling connections is the same as for
outgoing connections. The example demonstrates that handling the reads from a
certain connection can be delegated to another actor by naming it as the
-handler when sending the @scala[`Register` message]@java[message by the
`TcpMessage.register` method]. Writes can be sent from any
+handler when sending the
@scala[@scaladoc[Register](org.apache.pekko.io.Tcp.Register)
message]@java[message by the
@javadoc[TcpMessage.register](org.apache.pekko.io.TcpMessage#register(org.apache.pekko.actor.ActorRef))
method]. Writes can be sent from any
actor in the system to the connection actor (i.e. the actor which sent the
`Connected` message). The simplistic handler is defined as:
@@ -119,42 +119,42 @@ For a more complete sample which also takes into account
the possibility of
failures when sending please see @ref:[Throttling Reads and
Writes](#throttling-reads-and-writes) below.
The only difference to outgoing connections is that the internal actor managing
-the listen port—the sender of the `Bound` message—watches the actor
-which was named as the recipient for `Connected` messages in the
-@scala[`Bind` message]@java[`TcpMessage.bind` method]. When that actor
terminates the listen port will be
+the listen port—the sender of the @apidoc[org.apache.pekko.io.Tcp.Bound]
message—watches the actor
+which was named as the recipient for
@apidoc[org.apache.pekko.io.Tcp.Connected] messages in the
+@scala[@scaladoc[Bind](org.apache.pekko.io.Tcp.Bind)
message]@java[@javadoc[TcpMessage.bind](org.apache.pekko.io.TcpMessage#bind(org.apache.pekko.actor.ActorRef,java.net.InetSocketAddress,int))
method]. When that actor terminates the listen port will be
closed and all resources associated with it will be released; existing
connections will not be terminated at this point.
## Closing connections
-A connection can be closed by sending @scala[one of the commands `Close`,
`ConfirmedClose` or `Abort`]
-@java[a message by one of the methods `TcpMessage.close`,
`TcpMessage.confirmedClose` or `TcpMessage.abort`]
+A connection can be closed by sending @scala[one of the commands
@scaladoc[Close](org.apache.pekko.io.Tcp.Close$),
@scaladoc[ConfirmedClose](org.apache.pekko.io.Tcp.ConfirmedClose$) or
@scaladoc[Abort](org.apache.pekko.io.Tcp.Abort$)]
+@java[a message by one of the methods
@javadoc[TcpMessage.close](org.apache.pekko.io.TcpMessage#close()),
@javadoc[TcpMessage.confirmedClose](org.apache.pekko.io.TcpMessage#confirmedClose())
or @javadoc[TcpMessage.abort](org.apache.pekko.io.TcpMessage#abort())]
to the connection actor.
-@scala[`Close`]@java[`TcpMessage.close`] will close the connection by sending
a `FIN` message, but without waiting for confirmation from
+@scala[@scaladoc[Close](org.apache.pekko.io.Tcp.Close$)]@java[@javadoc[TcpMessage.close](org.apache.pekko.io.TcpMessage#close())]
will close the connection by sending a `FIN` message, but without waiting for
confirmation from
the remote endpoint. Pending writes will be flushed. If the close is
successful, the listener will be notified with
-`Closed`.
+@scala[@scaladoc[Closed](org.apache.pekko.io.Tcp.Closed$)]@java[@javadoc[Closed](org.apache.pekko.io.Tcp.Closed$)].
-@scala[`ConfirmedClose`]@java[`TcpMessage.confirmedClose`] will close the
sending direction of the connection by sending a `FIN` message, but data
+@scala[@scaladoc[ConfirmedClose](org.apache.pekko.io.Tcp.ConfirmedClose$)]@java[@javadoc[TcpMessage.confirmedClose](org.apache.pekko.io.TcpMessage#confirmedClose())]
will close the sending direction of the connection by sending a `FIN` message,
but data
will continue to be received until the remote endpoint closes the connection,
too. Pending writes will be flushed. If the close is
-successful, the listener will be notified with `ConfirmedClosed`.
+successful, the listener will be notified with
@scala[@scaladoc[ConfirmedClosed](org.apache.pekko.io.Tcp.ConfirmedClosed$)]@java[@javadoc[ConfirmedClosed](org.apache.pekko.io.Tcp.ConfirmedClosed$)].
-@scala[`Abort`]@java[`TcpMessage.abort`] will immediately terminate the
connection by sending a `RST` message to the remote endpoint. Pending
-writes will not be flushed. If the close is successful, the listener will be
notified with `Aborted`.
+@scala[@scaladoc[Abort](org.apache.pekko.io.Tcp.Abort$)]@java[@javadoc[TcpMessage.abort](org.apache.pekko.io.TcpMessage#abort())]
will immediately terminate the connection by sending a `RST` message to the
remote endpoint. Pending
+writes will not be flushed. If the close is successful, the listener will be
notified with
@scala[@scaladoc[Aborted](org.apache.pekko.io.Tcp.Aborted$)]@java[@javadoc[Aborted](org.apache.pekko.io.Tcp.Aborted$)].
-`PeerClosed` will be sent to the listener if the connection has been closed by
the remote endpoint. Per default, the
+@scala[@scaladoc[PeerClosed](org.apache.pekko.io.Tcp.PeerClosed$)]@java[@javadoc[PeerClosed](org.apache.pekko.io.Tcp.PeerClosed$)]
will be sent to the listener if the connection has been closed by the remote
endpoint. Per default, the
connection will then automatically be closed from this endpoint as well. To
support half-closed connections set the
-`keepOpenOnPeerClosed` member of the @scala[`Register`
message]@java[`TcpMessage.register` method] to `true` in which case the
connection stays open until
+`keepOpenOnPeerClosed` member of the
@scala[@scaladoc[Register](org.apache.pekko.io.Tcp.Register)
message]@java[@javadoc[TcpMessage.register](org.apache.pekko.io.TcpMessage#register(org.apache.pekko.actor.ActorRef,boolean,boolean))
method] to `true` in which case the connection stays open until
it receives one of the above close commands.
-`ErrorClosed` will be sent to the listener whenever an error happened that
forced the connection to be closed.
+@apidoc[org.apache.pekko.io.Tcp.ErrorClosed] will be sent to the listener
whenever an error happened that forced the connection to be closed.
-All close notifications are sub-types of `ConnectionClosed` so listeners who
do not need fine-grained close events
+All close notifications are sub-types of
@apidoc[org.apache.pekko.io.Tcp.ConnectionClosed] so listeners who do not need
fine-grained close events
may handle all close events in the same way.
## Writing to a connection
-Once a connection has been established data can be sent to it from any actor
in the form of a `Tcp.WriteCommand`.
+Once a connection has been established data can be sent to it from any actor
in the form of a
@apidoc[Tcp.WriteCommand](org.apache.pekko.io.Tcp.WriteCommand).
`Tcp.WriteCommand` is an abstract class with three concrete implementations:
Tcp.Write
@@ -162,28 +162,28 @@ Tcp.Write
A `ByteString` (as explained in @ref:[this section](io.md#bytestring)) models
one or more chunks of immutable
in-memory data with a maximum (total) size of 2 GB (2^31 bytes).
-Tcp.WriteFile
-: If you want to send "raw" data from a file you can do so efficiently with
the `Tcp.WriteFile` command.
+Tcp.WritePath
+: If you want to send "raw" data from a file you can do so efficiently with
the @apidoc[Tcp.WritePath](org.apache.pekko.io.Tcp.WritePath) command.
This allows you to designate a (contiguous) chunk of on-disk bytes for sending
across the connection without
-the need to first load them into the JVM memory. As such `Tcp.WriteFile` can
"hold" more than 2GB of data and
+the need to first load them into the JVM memory. As such `Tcp.WritePath` can
"hold" more than 2GB of data and
an "ack" event if required.
Tcp.CompoundWrite
:
-Sometimes, you might want to group (or interleave) several `Tcp.Write` and/or
`Tcp.WriteFile` commands into
-one atomic write command which gets written to the connection in one go. The
`Tcp.CompoundWrite` allows you
+Sometimes, you might want to group (or interleave) several
@apidoc[Tcp.Write](org.apache.pekko.io.Tcp.Write) and/or
@apidoc[Tcp.WritePath](org.apache.pekko.io.Tcp.WritePath) commands into
+one atomic write command which gets written to the connection in one go. The
@apidoc[Tcp.CompoundWrite](org.apache.pekko.io.Tcp.CompoundWrite) allows you
to do just that and offers three benefits:
1. As explained in the following section the TCP connection actor can only
handle one single write command at a time.
-By combining several writes into one `CompoundWrite` you can have them be sent
across the connection with
+By combining several writes into one
@apidoc[CompoundWrite](org.apache.pekko.io.Tcp.CompoundWrite) you can have them
be sent across the connection with
minimum overhead and without the need to spoon feed them to the connection
actor via an *ACK-based* message
protocol.
- 2. Because a `WriteCommand` is atomic you can be sure that no other actor can
"inject" other writes into your
-series of writes if you combine them into one single `CompoundWrite`. In
scenarios where several actors write
+ 2. Because a @apidoc[org.apache.pekko.io.Tcp.WriteCommand] is atomic you can
be sure that no other actor can "inject" other writes into your
+series of writes if you combine them into one single
@apidoc[CompoundWrite](org.apache.pekko.io.Tcp.CompoundWrite). In scenarios
where several actors write
to the same connection this can be an important feature which can be somewhat
hard to achieve otherwise.
- 3. The "sub writes" of a `CompoundWrite` are regular @scala[`Write` or
`WriteFile` commands]@java[messages by `TcpMessage.write` or
`TcpMessage.writeFile` methods] that themselves can request
+ 3. The "sub writes" of a
@apidoc[CompoundWrite](org.apache.pekko.io.Tcp.CompoundWrite) are regular
@scala[@scaladoc[Write](org.apache.pekko.io.Tcp.Write) or
@scaladoc[WritePath](org.apache.pekko.io.Tcp.WritePath) commands]@java[messages
by
@javadoc[TcpMessage.write](org.apache.pekko.io.TcpMessage#write(org.apache.pekko.util.ByteString,org.apache.pekko.io.Tcp.Event))
or
@javadoc[TcpMessage.writePath](org.apache.pekko.io.TcpMessage#writePath(java.nio.file.Path,long,long,org.apache.pekko.i
[...]
"ack" events. These ACKs are sent out as soon as the respective "sub write"
has been completed. This allows you to
-attach more than one ACK to a @scala[`Write` or `WriteFile`]@java[message by
`TcpMessage.write` or `TcpMessage.writeFile`] (by combining it with an empty
write that itself requests
-an ACK) or to have the connection actor acknowledge the progress of
transmitting the `CompoundWrite` by sending
+attach more than one ACK to a
@scala[@scaladoc[Write](org.apache.pekko.io.Tcp.Write) or
@scaladoc[WritePath](org.apache.pekko.io.Tcp.WritePath)]@java[message by
@javadoc[TcpMessage.write](org.apache.pekko.io.TcpMessage#write(org.apache.pekko.util.ByteString,org.apache.pekko.io.Tcp.Event))
or
@javadoc[TcpMessage.writePath](org.apache.pekko.io.TcpMessage#writePath(java.nio.file.Path,long,long,org.apache.pekko.io.Tcp.Event))]
(by combining it with an empty write that itself requests
+an ACK) or to have the connection actor acknowledge the progress of
transmitting the @apidoc[CompoundWrite](org.apache.pekko.io.Tcp.CompoundWrite)
by sending
out intermediate ACKs at arbitrary points.
@@ -196,22 +196,22 @@ needs to be handled at the user level, for both writes
and reads.
For back-pressuring writes there are three modes of operation
- * *ACK-based:* every `Write` command carries an arbitrary object, and if
-this object is not `Tcp.NoAck` then it will be returned to the sender of
+ * *ACK-based:* every @apidoc[org.apache.pekko.io.Tcp.Write] command carries
an arbitrary object, and if
+this object is not @apidoc[org.apache.pekko.io.Tcp.NoAck] then it will be
returned to the sender of
the `Write` upon successfully writing all contained data to the
socket. If no other write is initiated before having received this
acknowledgement then no failures can happen due to buffer overrun.
* *NACK-based:* every write which arrives while a previous write is not yet
-completed will be replied to with a `CommandFailed` message containing
+completed will be replied to with a
@apidoc[org.apache.pekko.io.Tcp.CommandFailed] message containing
the failed write. Just relying on this mechanism requires the implemented
protocol to tolerate skipping writes (e.g. if each write is a valid message
on its own and it is not required that all are delivered). This mode is
enabled by setting the `useResumeWriting` flag to `false` within the
-@scala[`Register` message]@java[message by the `TcpMessage.register` method]
during connection activation.
+ @scala[@scaladoc[Register](org.apache.pekko.io.Tcp.Register)
message]@java[@javadoc[TcpMessage.register](org.apache.pekko.io.TcpMessage#register(org.apache.pekko.actor.ActorRef,boolean,boolean))
method] during connection activation.
* *NACK-based with write suspending:* this mode is very similar to the
NACK-based one, but once a single write has failed no further writes will
-succeed until a @scala[`ResumeWriting` message]@java[message by the
`TcpMessage.resumeWriting` method] is received. This message will
-be answered with a `WritingResumed` message once the last accepted
+succeed until a
@scala[@scaladoc[ResumeWriting](org.apache.pekko.io.Tcp.ResumeWriting$)
message]@java[message by the
@javadoc[TcpMessage.resumeWriting](org.apache.pekko.io.TcpMessage#resumeWriting())
method] is received. This message will
+be answered with a @apidoc[org.apache.pekko.io.Tcp.WritingResumed] message
once the last accepted
write has completed. If the actor driving the connection implements buffering
and resends the NACK’ed messages after having awaited the
`WritingResumed` signal then every message is delivered exactly once
@@ -224,11 +224,11 @@ available @scala[@extref[on
GitHub](github:docs/src/test/scala/docs/io/EchoServe
For back-pressuring reads there are two modes of operation
* *Push-reading:* in this mode the connection actor sends the registered
reader actor
-incoming data as soon as available as `Received` events. Whenever the reader
actor
-wants to signal back-pressure to the remote TCP endpoint it can send a
@scala[`SuspendReading` message]@java[message by the
`TcpMessage.suspendReading` method]
+incoming data as soon as available as
@apidoc[org.apache.pekko.io.Tcp.Received] events. Whenever the reader actor
+wants to signal back-pressure to the remote TCP endpoint it can send a
@scala[@scaladoc[SuspendReading](org.apache.pekko.io.Tcp.SuspendReading$)
message]@java[message by the
@javadoc[TcpMessage.suspendReading](org.apache.pekko.io.TcpMessage#suspendReading())
method]
to the connection actor to indicate that it wants to suspend the
reception of new data. No `Received` events will arrive until a corresponding
-`ResumeReading` is sent indicating that the receiver actor is ready again.
+@scala[@scaladoc[ResumeReading](org.apache.pekko.io.Tcp.ResumeReading$)]@java[message
from
@javadoc[TcpMessage.resumeReading](org.apache.pekko.io.TcpMessage#resumeReading())]
is sent indicating that the receiver actor is ready again.
* *Pull-reading:* after sending a `Received` event the connection
actor automatically suspends accepting data from the socket until the reader
actor signals
with a `ResumeReading` message that it is ready to process more input data.
Hence
@@ -248,7 +248,7 @@ For proper function of the following example it is
important to configure the
connection to remain half-open when the remote side closed its writing end:
this allows the example `EchoHandler` to write all outstanding data back
to the client before fully closing the connection. This is enabled using a flag
-upon connection activation (observe the @scala[`Register`
message]@java[`TcpMessage.register` method]):
+upon connection activation (observe the
@scala[@scaladoc[Register](org.apache.pekko.io.Tcp.Register)
message]@java[@javadoc[TcpMessage.register](org.apache.pekko.io.TcpMessage#register(org.apache.pekko.actor.ActorRef,boolean,boolean))
method]):
Scala
: @@snip [EchoServer.scala](/docs/src/test/scala/docs/io/EchoServer.scala) {
#echo-manager }
@@ -282,7 +282,7 @@ behavior; otherwise we send the next buffered chunk and
stay waiting for
the next `Ack`.
Back-pressure can be propagated also across the reading side back to the writer
-on the other end of the connection by sending the @scala[`SuspendReading`
command]@java[message by the `TcpMessage.suspendReading` method]
+on the other end of the connection by sending the
@scala[@scaladoc[SuspendReading](org.apache.pekko.io.Tcp.SuspendReading$)
command]@java[message by the
@javadoc[TcpMessage.suspendReading](org.apache.pekko.io.TcpMessage#suspendReading())
method]
to the connection actor. This will lead to no data being read from the
socket anymore (although this does happen after a delay because it takes some
time until the connection actor processes this command, hence appropriate
@@ -300,7 +300,7 @@ Scala
Java
: @@snip
[EchoHandler.java](/docs/src/test/java/jdocs/io/japi/EchoHandler.java) {
#echo-handler }
-The principle here is to keep writing until a `CommandFailed` is
+The principle here is to keep writing until a
@apidoc[org.apache.pekko.io.Tcp.CommandFailed] is
received, using acknowledgements only to prune the resend buffer. When such a
failure was received, transition into a different state for handling and handle
resending of all queued data:
@@ -313,7 +313,7 @@ Java
It should be noted that all writes which are currently buffered have also been
sent to the connection actor upon entering this state, which means that the
-@scala[`ResumeWriting` message]@java[message by the `TcpMessage.resumeWriting`
method] is enqueued after those writes, leading to the
+@scala[@scaladoc[ResumeWriting](org.apache.pekko.io.Tcp.ResumeWriting$)
message]@java[message by the
@javadoc[TcpMessage.resumeWriting](org.apache.pekko.io.TcpMessage#resumeWriting())
method] is enqueued after those writes, leading to the
reception of all outstanding `CommandFailed` messages (which are ignored
in this state) before receiving the `WritingResumed` signal. That latter
message is sent by the connection actor only once the internally queued write
@@ -360,13 +360,13 @@ Java
The idea here is that reading is not resumed until the previous write has been
completely acknowledged by the connection actor. Every pull mode connection
actor starts from suspended state. To start the flow of data we send a
-@scala[`ResumeReading`]@java[message by the `TcpMessage.resumeReading` method]
in the `preStart` method to tell the connection actor that
+@scala[@scaladoc[ResumeReading](org.apache.pekko.io.Tcp.ResumeReading$)]@java[message
by the
@javadoc[TcpMessage.resumeReading](org.apache.pekko.io.TcpMessage#resumeReading())
method] in the `preStart` method to tell the connection actor that
we are ready to receive the first chunk of data. Since we only resume reading
when
the previous data chunk has been completely written there is no need for
maintaining
a buffer.
To enable pull reading on an outbound connection the `pullMode` parameter of
-the @scala[`Connect`]@java[`TcpMessage.connect` method] should be set to
`true`:
+the
@scala[@scaladoc[Connect](org.apache.pekko.io.Tcp.Connect)]@java[@javadoc[TcpMessage.connect](org.apache.pekko.io.TcpMessage#connect(java.net.InetSocketAddress,java.net.InetSocketAddress,java.lang.Iterable,scala.concurrent.duration.FiniteDuration,boolean))
method] should be set to `true`:
Scala
: @@snip
[ReadBackPressure.scala](/docs/src/test/scala/docs/io/ReadBackPressure.scala) {
#pull-mode-connect }
@@ -378,7 +378,7 @@ Java
The previous section demonstrated how to enable pull reading mode for outbound
connections but it is possible to create a listener actor with this mode of
reading
-by setting the `pullMode` parameter of the @scala[`Bind`
command]@java[`TcpMessage.bind` method] to `true`:
+by setting the `pullMode` parameter of the
@scala[@scaladoc[Bind](org.apache.pekko.io.Tcp.Bind) command]@java[message by
the
@javadoc[TcpMessage.bind](org.apache.pekko.io.TcpMessage#bind(org.apache.pekko.actor.ActorRef,java.net.InetSocketAddress,int,java.lang.Iterable,boolean))
method] to `true`:
Scala
: @@snip
[ReadBackPressure.scala](/docs/src/test/scala/docs/io/ReadBackPressure.scala) {
#pull-mode-bind }
@@ -392,10 +392,10 @@ actor will use pull mode reading.
Another effect of this setting is that in addition of setting all inbound
connections to
pull mode, accepting connections becomes pull based, too. This means that
after handling
one (or more) `Connected` events the listener actor has to be resumed by
sending
-it a @scala[`ResumeAccepting` message]@java[message by the
`TcpMessage.resumeAccepting` method].
+it a
@scala[@scaladoc[ResumeAccepting](org.apache.pekko.io.Tcp.ResumeAccepting)
message]@java[message by the
@javadoc[TcpMessage.resumeAccepting](org.apache.pekko.io.TcpMessage#resumeAccepting(int))
method].
Listener actors with pull mode start suspended so to start accepting
connections
-a @scala[`ResumeAccepting` command]@java[message by the
`TcpMessage.resumeAccepting` method] has to be sent to the listener actor after
binding was successful:
+a @scala[@scaladoc[ResumeAccepting](org.apache.pekko.io.Tcp.ResumeAccepting)
command]@java[message by the
@javadoc[TcpMessage.resumeAccepting](org.apache.pekko.io.TcpMessage#resumeAccepting(int))
method] has to be sent to the listener actor after binding was successful:
Scala
: @@snip
[ReadBackPressure.scala](/docs/src/test/scala/docs/io/ReadBackPressure.scala) {
#pull-accepting #pull-accepting-cont }
@@ -405,6 +405,6 @@ Java
As shown in the example, after handling an incoming connection we need to
resume accepting again.
-The @scala[`ResumeAccepting`]@java[`TcpMessage.resumeAccepting` method]
accepts a `batchSize` parameter that specifies how
+The
@scala[@scaladoc[ResumeAccepting](org.apache.pekko.io.Tcp.ResumeAccepting)]@java[@javadoc[TcpMessage.resumeAccepting](org.apache.pekko.io.TcpMessage#resumeAccepting(int))
method] accepts a `batchSize` parameter that specifies how
many new connections are accepted before a next `ResumeAccepting` message
is needed to resume handling of new connections.
diff --git a/docs/src/main/paradox/io-udp.md b/docs/src/main/paradox/io-udp.md
index 5dbc8b68bd..d49478bf55 100644
--- a/docs/src/main/paradox/io-udp.md
+++ b/docs/src/main/paradox/io-udp.md
@@ -53,7 +53,7 @@ destinations; in this example it will send any UTF-8 encoded
@@@ note
The simple sender will not shut itself down because it cannot know when you
-are done with it. You will need to send it a `PoisonPill` when you
+are done with it. You will need to send it a
@apidoc[org.apache.pekko.actor.PoisonPill] when you
want to close the ephemeral port the sender is bound to.
@@@
@@ -67,20 +67,20 @@ Java
: @@snip [UdpDocTest.java](/docs/src/test/java/jdocs/io/UdpDocTest.java) {
#listener }
If you want to implement a UDP server which listens on a socket for incoming
-datagrams then you need to use the @scala[`Bind`]@java[`UdpMessage.bind`]
message as shown above. The
+datagrams then you need to use the
@scala[@scaladoc[Bind](org.apache.pekko.io.Udp.Bind)]@java[@javadoc[UdpMessage.bind](org.apache.pekko.io.UdpMessage#bind(org.apache.pekko.actor.ActorRef,java.net.InetSocketAddress,java.lang.Iterable))]
message as shown above. The
local address specified may have a zero port in which case the operating system
will automatically choose a free port and assign it to the new socket. Which
port was actually bound can be found out by inspecting the `Bound`
message.
-The sender of the `Bound` message is the actor which manages the new
-socket. Sending datagrams is achieved by using the
@scala[`Send`]@java[`UdpMessage.send`] message
-and the socket can be closed by sending a
@scala[`Unbind`]@java[`UdpMessage.unbind`] message, in which
-case the socket actor will reply with a `Unbound` notification.
+The sender of the @apidoc[org.apache.pekko.io.Udp.Bound] message is the actor
which manages the new
+socket. Sending datagrams is achieved by using the
@scala[@scaladoc[Send](org.apache.pekko.io.Udp.Send)]@java[@javadoc[UdpMessage.send](org.apache.pekko.io.UdpMessage#send(org.apache.pekko.util.ByteString,java.net.InetSocketAddress))]
message
+and the socket can be closed by sending a
@scala[@scaladoc[Unbind](org.apache.pekko.io.Udp.Unbind$)]@java[@javadoc[UdpMessage.unbind](org.apache.pekko.io.UdpMessage#unbind())]
message, in which
+case the socket actor will reply with a
@apidoc[org.apache.pekko.io.Udp.Unbound] notification.
Received datagrams are sent to the actor designated in the `Bind`
message, whereas the `Bound` message will be sent to the sender of the
-@scala[`Bind`]@java[`UdpMessage.bind`].
+@scala[@scaladoc[Bind](org.apache.pekko.io.Udp.Bind)]@java[@javadoc[UdpMessage.bind](org.apache.pekko.io.UdpMessage#bind(org.apache.pekko.actor.ActorRef,java.net.InetSocketAddress,java.lang.Iterable))].
## Connected UDP
@@ -101,12 +101,12 @@ the biggest difference is the absence of remote address
information in
## UDP Multicast
-Pekko provides a way to control various options of `DatagramChannel` through
the
-`org.apache.pekko.io.Inet.SocketOption` interface. The example below shows
+Pekko provides a way to control various options of
@javadoc[DatagramChannel](java.nio.channels.DatagramChannel) through the
+@apidoc[org.apache.pekko.io.Inet.SocketOption] interface. The example below
shows
how to setup a receiver of multicast messages using IPv6 protocol.
-To select a Protocol Family you must extend
`org.apache.pekko.io.Inet.DatagramChannelCreator`
-class which @scala[extends]@java[implements]
`org.apache.pekko.io.Inet.SocketOption`. Provide custom logic
+To select a Protocol Family you must extend
@apidoc[org.apache.pekko.io.Inet.DatagramChannelCreator]
+class which @scala[extends]@java[implements]
@apidoc[org.apache.pekko.io.Inet.SocketOption]. Provide custom logic
for opening a datagram channel by overriding `create` method.
Scala
@@ -123,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[`Udp.Bind`]@java[`UdpMessage.bind`]
message.
+Socket options must be provided to
@scala[@scaladoc[Bind](org.apache.pekko.io.Udp.Bind)]@java[@javadoc[UdpMessage.bind](org.apache.pekko.io.UdpMessage#bind(org.apache.pekko.actor.ActorRef,java.net.InetSocketAddress,java.lang.Iterable))]
message.
Scala
: @@snip
[ScalaUdpMulticast.scala](/docs/src/test/scala/docs/io/ScalaUdpMulticast.scala)
{ #bind }
diff --git a/docs/src/main/paradox/typed/fsm.md
b/docs/src/main/paradox/typed/fsm.md
index 1e951f7361..548cf26eb4 100644
--- a/docs/src/main/paradox/typed/fsm.md
+++ b/docs/src/main/paradox/typed/fsm.md
@@ -34,7 +34,7 @@ Scala
Java
: @@snip
[FSMSocTest.java](/actor-typed-tests/src/test/java/jdocs/org/apache/pekko/typed/FSMDocTest.java)
{ #storing-state }
-Each state becomes a distinct behavior and after processing a message the next
state in the form of a `Behavior`
+Each state becomes a distinct behavior and after processing a message the next
state in the form of a @apidoc[typed.Behavior]
is returned.
Scala
@@ -44,18 +44,18 @@ Java
: @@snip
[FSMSocTest.java](/actor-typed-tests/src/test/java/jdocs/org/apache/pekko/typed/FSMDocTest.java)
{ #simple-state}
@@@ div { .group-scala }
-The method `idle` above makes use of `Behaviors.unhandled` which advises the
system to reuse the previous behavior,
+The method `idle` above makes use of
@apidoc[Behaviors.unhandled](typed.*.Behaviors$)
{scala="#unhandled[T]:org.apache.pekko.actor.typed.Behavior[T]"
java="#unhandled()"} which advises the system to reuse the previous behavior,
including the hint that the message has not been handled.
There are two related behaviors:
-- return `Behaviors.empty` as next behavior in case you reached a state where
you don't expect messages any more.
+- return @apidoc[Behaviors.empty](typed.*.Behaviors$)
{scala="#empty[T]:org.apache.pekko.actor.typed.Behavior[T]" java="#empty()"} as
next behavior in case you reached a state where you don't expect messages any
more.
For instance if an actor only waits until all spawned child actors stopped.
Unhandled messages are still logged with this behavior.
-- return `Behaviors.ignore` as next behavior in case you don't care about
unhandled messages.
+- return @apidoc[Behaviors.ignore](typed.*.Behaviors$)
{scala="#ignore[T]:org.apache.pekko.actor.typed.Behavior[T]" java="#ignore()"}
as next behavior in case you don't care about unhandled messages.
All messages sent to an actor with such a behavior are simply dropped and
ignored (without logging)
@@@
-To set state timeouts use `Behaviors.withTimers` along with a
`startSingleTimer`.
+To set state timeouts use @apidoc[Behaviors.withTimers](typed.*.Behaviors$)
{scala="#withTimers[T](factory:org.apache.pekko.actor.typed.scaladsl.TimerScheduler[T]=%3Eorg.apache.pekko.actor.typed.Behavior[T]):org.apache.pekko.actor.typed.Behavior[T]"
java="#withTimers(org.apache.pekko.japi.function.Function)"} along with a
@apidoc[startSingleTimer](typed.*.TimerScheduler)
{scala="#startSingleTimer(key:Any,msg:T,delay:scala.concurrent.duration.FiniteDuration):Unit"
java="#startSingleTimer( [...]
## Example project
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
