From 655e9e330080252f17afc8facab0fa61e38823b1 Mon Sep 17 00:00:00 2001 From: Mathias Date: Wed, 25 Sep 2013 16:58:52 +0200 Subject: [PATCH] =doc #3581 Add "Writing to a connection" section to IO docs --- akka-docs/rst/java/io-tcp.rst | 37 ++++++++++++++++++++++++++++++++++ akka-docs/rst/java/io.rst | 2 ++ akka-docs/rst/scala/io-tcp.rst | 37 ++++++++++++++++++++++++++++++++++ akka-docs/rst/scala/io.rst | 2 ++ 4 files changed, 78 insertions(+) diff --git a/akka-docs/rst/java/io-tcp.rst b/akka-docs/rst/java/io-tcp.rst index 73164b21de..bc271c777a 100644 --- a/akka-docs/rst/java/io-tcp.rst +++ b/akka-docs/rst/java/io-tcp.rst @@ -125,6 +125,43 @@ it receives one of the above close commands. All close notifications are sub-types of ``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``. +``Tcp.WriteCommand`` is an abstract class with three concrete implementations: + +Tcp.Write + The simplest ``WriteCommand`` implementation which wraps a ``ByteString`` instance and an "ack" event. + A ``ByteString`` (as explained in :ref:`this section `) 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. + This allows you do 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 + 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 + 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 + 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 + 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 ``Write`` or ``WriteFile`` commands that themselves can request + "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 ``Write`` or ``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 + out intermediate ACKs at arbitrary points. + Throttling Reads and Writes --------------------------- diff --git a/akka-docs/rst/java/io.rst b/akka-docs/rst/java/io.rst index a6c4027a16..1cbb9fbe9d 100644 --- a/akka-docs/rst/java/io.rst +++ b/akka-docs/rst/java/io.rst @@ -85,6 +85,8 @@ nacked messages it may need to keep a buffer of pending messages. the I/O driver has successfully processed the write. The Ack/Nack protocol described here is a means of flow control not error handling. In other words, data may still be lost, even if every write is acknowledged. +.. _ByteString: + ByteString ^^^^^^^^^^ diff --git a/akka-docs/rst/scala/io-tcp.rst b/akka-docs/rst/scala/io-tcp.rst index c60b360f0d..c898dfb129 100644 --- a/akka-docs/rst/scala/io-tcp.rst +++ b/akka-docs/rst/scala/io-tcp.rst @@ -126,6 +126,43 @@ it receives one of the above close commands. All close notifications are sub-types of ``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``. +``Tcp.WriteCommand`` is an abstract class with three concrete implementations: + +Tcp.Write + The simplest ``WriteCommand`` implementation which wraps a ``ByteString`` instance and an "ack" event. + A ``ByteString`` (as explained in :ref:`this section `) 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. + This allows you do 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 + 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 + 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 + 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 + 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 ``Write`` or ``WriteFile`` commands that themselves can request + "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 ``Write`` or ``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 + out intermediate ACKs at arbitrary points. + Throttling Reads and Writes --------------------------- diff --git a/akka-docs/rst/scala/io.rst b/akka-docs/rst/scala/io.rst index ecb944c83a..88e1e64d10 100644 --- a/akka-docs/rst/scala/io.rst +++ b/akka-docs/rst/scala/io.rst @@ -90,6 +90,8 @@ nacked messages it may need to keep a buffer of pending messages. the I/O driver has successfully processed the write. The Ack/Nack protocol described here is a means of flow control not error handling. In other words, data may still be lost, even if every write is acknowledged. +.. _ByteString: + ByteString ^^^^^^^^^^