From 163f0f972751f2f8bf1c16686a2a1439a937ca80 Mon Sep 17 00:00:00 2001 From: Olli Helenius Date: Thu, 17 Nov 2016 13:31:44 +0200 Subject: [PATCH] Fix formatting of plural ByteStrings in docs (#21792) --- akka-docs/rst/java/stream/stream-cookbook.rst | 20 +++++++++---------- akka-docs/rst/java/stream/stream-io.rst | 4 ++-- .../rst/scala/stream/stream-cookbook.rst | 20 +++++++++---------- akka-docs/rst/scala/stream/stream-io.rst | 4 ++-- 4 files changed, 24 insertions(+), 24 deletions(-) diff --git a/akka-docs/rst/java/stream/stream-cookbook.rst b/akka-docs/rst/java/stream/stream-cookbook.rst index 1a673e2e78..1cc819a294 100644 --- a/akka-docs/rst/java/stream/stream-cookbook.rst +++ b/akka-docs/rst/java/stream/stream-cookbook.rst @@ -72,7 +72,7 @@ Rather, use ``limit`` or ``take`` to ensure that the resulting ``List`` will con Calculating the digest of a ByteString stream --------------------------------------------- -**Situation:** A stream of bytes is given as a stream of ``ByteStrings`` and we want to calculate the cryptographic digest +**Situation:** A stream of bytes is given as a stream of ``ByteString`` s and we want to calculate the cryptographic digest of the stream. This recipe uses a :class:`GraphStage` to host a mutable :class:`MessageDigest` class (part of the Java Cryptography @@ -80,7 +80,7 @@ API) and update it with the bytes arriving from the stream. When the stream star stage is called, which just bubbles up the ``pull`` event to its upstream. As a response to this pull, a ByteString chunk will arrive (``onPush``) which we use to update the digest, then it will pull for the next chunk. -Eventually the stream of ``ByteStrings`` depletes and we get a notification about this event via ``onUpstreamFinish``. +Eventually the stream of ``ByteString`` s depletes and we get a notification about this event via ``onUpstreamFinish``. At this point we want to emit the digest value, but we cannot do it with ``push`` in this handler directly since there may be no downstream demand. Instead we call ``emit`` which will temporarily replace the handlers, emit the provided value when demand comes in and then reset the stage state. It will then complete the stage. @@ -94,11 +94,11 @@ demand comes in and then reset the stage state. It will then complete the stage. Parsing lines from a stream of ByteStrings ------------------------------------------ -**Situation:** A stream of bytes is given as a stream of ``ByteStrings`` containing lines terminated by line ending +**Situation:** A stream of bytes is given as a stream of ``ByteString`` s containing lines terminated by line ending characters (or, alternatively, containing binary frames delimited by a special delimiter byte sequence) which needs to be parsed. -The :class:`Framing` helper class contains a convenience method to parse messages from a stream of ``ByteStrings``: +The :class:`Framing` helper class contains a convenience method to parse messages from a stream of ``ByteString`` s: .. includecode:: ../code/docs/stream/javadsl/cookbook/RecipeParseLines.java#parse-lines @@ -336,8 +336,8 @@ Working with IO Chunking up a stream of ByteStrings into limited size ByteStrings ----------------------------------------------------------------- -**Situation:** Given a stream of ByteStrings we want to produce a stream of ByteStrings containing the same bytes in -the same sequence, but capping the size of ByteStrings. In other words we want to slice up ByteStrings into smaller +**Situation:** Given a stream of ``ByteString`` s we want to produce a stream of ``ByteString`` s containing the same bytes in +the same sequence, but capping the size of ``ByteString`` s. In other words we want to slice up ``ByteString`` s into smaller chunks if they exceed a size threshold. This can be achieved with a single :class:`GraphStage`. The main logic of our stage is in ``emitChunk()`` @@ -357,7 +357,7 @@ the incoming chunk by appending to the end of the buffer. Limit the number of bytes passing through a stream of ByteStrings ----------------------------------------------------------------- -**Situation:** Given a stream of ByteStrings we want to fail the stream if more than a given maximum of bytes has been +**Situation:** Given a stream of ``ByteString`` s we want to fail the stream if more than a given maximum of bytes has been consumed. This recipe uses a :class:`GraphStage` to implement the desired feature. In the only handler we override, @@ -371,9 +371,9 @@ we signal failure, otherwise we forward the chunk we have received. Compact ByteStrings in a stream of ByteStrings ---------------------------------------------- -**Situation:** After a long stream of transformations, due to their immutable, structural sharing nature ByteStrings may +**Situation:** After a long stream of transformations, due to their immutable, structural sharing nature ``ByteString`` s may refer to multiple original ByteString instances unnecessarily retaining memory. As the final step of a transformation -chain we want to have clean copies that are no longer referencing the original ByteStrings. +chain we want to have clean copies that are no longer referencing the original ``ByteString`` s. The recipe is a simple use of map, calling the ``compact()`` method of the :class:`ByteString` elements. This does copying of the underlying arrays, so this should be the last element of a long chain if used. @@ -383,7 +383,7 @@ copying of the underlying arrays, so this should be the last element of a long c Injecting keep-alive messages into a stream of ByteStrings ---------------------------------------------------------- -**Situation:** Given a communication channel expressed as a stream of ByteStrings we want to inject keep-alive messages +**Situation:** Given a communication channel expressed as a stream of ``ByteString`` s we want to inject keep-alive messages but only if this does not interfere with normal traffic. There is a built-in operation that allows to do this directly: diff --git a/akka-docs/rst/java/stream/stream-io.rst b/akka-docs/rst/java/stream/stream-io.rst index 69265c7c99..0e1080bf77 100644 --- a/akka-docs/rst/java/stream/stream-io.rst +++ b/akka-docs/rst/java/stream/stream-io.rst @@ -22,7 +22,7 @@ which will emit an :class:`IncomingConnection` element for each new connection t .. image:: ../../images/tcp-stream-bind.png Next, we simply handle *each* incoming connection using a :class:`Flow` which will be used as the processing stage -to handle and emit ByteStrings from and to the TCP Socket. Since one :class:`ByteString` does not have to necessarily +to handle and emit ``ByteString`` s from and to the TCP Socket. Since one :class:`ByteString` does not have to necessarily correspond to exactly one line of text (the client might be sending the line in chunks) we use the ``delimiter`` helper Flow from ``akka.stream.javadsl.Framing`` to chunk the inputs up into actual lines of text. The last boolean argument indicates that we require an explicit line ending even for the last message before the connection is closed. @@ -89,7 +89,7 @@ it makes sense to make the Server initiate the conversation by emitting a "hello .. includecode:: ../code/docs/stream/io/StreamTcpDocTest.java#welcome-banner-chat-server To emit the initial message we merge a ``Source`` with a single element, after the command processing but before the -framing and transformation to ``ByteStrings`` this way we do not have to repeat such logic. +framing and transformation to ``ByteString`` s this way we do not have to repeat such logic. In this example both client and server may need to close the stream based on a parsed command - ``BYE`` in the case of the server, and ``q`` in the case of the client. This is implemented by using a custom :class:`GraphStage` diff --git a/akka-docs/rst/scala/stream/stream-cookbook.rst b/akka-docs/rst/scala/stream/stream-cookbook.rst index b2a599371d..8655b3841b 100644 --- a/akka-docs/rst/scala/stream/stream-cookbook.rst +++ b/akka-docs/rst/scala/stream/stream-cookbook.rst @@ -72,7 +72,7 @@ Rather, use ``limit`` or ``take`` to ensure that the resulting ``Seq`` will cont Calculating the digest of a ByteString stream --------------------------------------------- -**Situation:** A stream of bytes is given as a stream of ``ByteStrings`` and we want to calculate the cryptographic digest +**Situation:** A stream of bytes is given as a stream of ``ByteString`` s and we want to calculate the cryptographic digest of the stream. This recipe uses a :class:`GraphStage` to host a mutable :class:`MessageDigest` class (part of the Java Cryptography @@ -80,7 +80,7 @@ API) and update it with the bytes arriving from the stream. When the stream star stage is called, which just bubbles up the ``pull`` event to its upstream. As a response to this pull, a ByteString chunk will arrive (``onPush``) which we use to update the digest, then it will pull for the next chunk. -Eventually the stream of ``ByteStrings`` depletes and we get a notification about this event via ``onUpstreamFinish``. +Eventually the stream of ``ByteString`` s depletes and we get a notification about this event via ``onUpstreamFinish``. At this point we want to emit the digest value, but we cannot do it with ``push`` in this handler directly since there may be no downstream demand. Instead we call ``emit`` which will temporarily replace the handlers, emit the provided value when demand comes in and then reset the stage state. It will then complete the stage. @@ -92,11 +92,11 @@ demand comes in and then reset the stage state. It will then complete the stage. Parsing lines from a stream of ByteStrings ------------------------------------------ -**Situation:** A stream of bytes is given as a stream of ``ByteStrings`` containing lines terminated by line ending +**Situation:** A stream of bytes is given as a stream of ``ByteString`` s containing lines terminated by line ending characters (or, alternatively, containing binary frames delimited by a special delimiter byte sequence) which needs to be parsed. -The :class:`Framing` helper object contains a convenience method to parse messages from a stream of ``ByteStrings``: +The :class:`Framing` helper object contains a convenience method to parse messages from a stream of ``ByteString`` s: .. includecode:: ../code/docs/stream/cookbook/RecipeParseLines.scala#parse-lines @@ -329,8 +329,8 @@ Working with IO Chunking up a stream of ByteStrings into limited size ByteStrings ----------------------------------------------------------------- -**Situation:** Given a stream of ByteStrings we want to produce a stream of ByteStrings containing the same bytes in -the same sequence, but capping the size of ByteStrings. In other words we want to slice up ByteStrings into smaller +**Situation:** Given a stream of ``ByteString`` s we want to produce a stream of ``ByteString`` s containing the same bytes in +the same sequence, but capping the size of ``ByteString`` s. In other words we want to slice up ``ByteString`` s into smaller chunks if they exceed a size threshold. This can be achieved with a single :class:`GraphStage`. The main logic of our stage is in ``emitChunk()`` @@ -348,7 +348,7 @@ the incoming chunk by appending to the end of the buffer. Limit the number of bytes passing through a stream of ByteStrings ----------------------------------------------------------------- -**Situation:** Given a stream of ByteStrings we want to fail the stream if more than a given maximum of bytes has been +**Situation:** Given a stream of ``ByteString`` s we want to fail the stream if more than a given maximum of bytes has been consumed. This recipe uses a :class:`GraphStage` to implement the desired feature. In the only handler we override, @@ -360,9 +360,9 @@ we signal failure, otherwise we forward the chunk we have received. Compact ByteStrings in a stream of ByteStrings ---------------------------------------------- -**Situation:** After a long stream of transformations, due to their immutable, structural sharing nature ByteStrings may +**Situation:** After a long stream of transformations, due to their immutable, structural sharing nature ``ByteString`` s may refer to multiple original ByteString instances unnecessarily retaining memory. As the final step of a transformation -chain we want to have clean copies that are no longer referencing the original ByteStrings. +chain we want to have clean copies that are no longer referencing the original ``ByteString`` s. The recipe is a simple use of map, calling the ``compact()`` method of the :class:`ByteString` elements. This does copying of the underlying arrays, so this should be the last element of a long chain if used. @@ -372,7 +372,7 @@ copying of the underlying arrays, so this should be the last element of a long c Injecting keep-alive messages into a stream of ByteStrings ---------------------------------------------------------- -**Situation:** Given a communication channel expressed as a stream of ByteStrings we want to inject keep-alive messages +**Situation:** Given a communication channel expressed as a stream of ``ByteString`` s we want to inject keep-alive messages but only if this does not interfere with normal traffic. There is a built-in operation that allows to do this directly: diff --git a/akka-docs/rst/scala/stream/stream-io.rst b/akka-docs/rst/scala/stream/stream-io.rst index c04c4d7109..d58eb2fee8 100644 --- a/akka-docs/rst/scala/stream/stream-io.rst +++ b/akka-docs/rst/scala/stream/stream-io.rst @@ -22,7 +22,7 @@ which will emit an :class:`IncomingConnection` element for each new connection t .. image:: ../../images/tcp-stream-bind.png Next, we simply handle *each* incoming connection using a :class:`Flow` which will be used as the processing stage -to handle and emit ByteStrings from and to the TCP Socket. Since one :class:`ByteString` does not have to necessarily +to handle and emit ``ByteString`` s from and to the TCP Socket. Since one :class:`ByteString` does not have to necessarily correspond to exactly one line of text (the client might be sending the line in chunks) we use the ``Framing.delimiter`` helper Flow to chunk the inputs up into actual lines of text. The last boolean argument indicates that we require an explicit line ending even for the last message before the connection is closed. @@ -89,7 +89,7 @@ it makes sense to make the Server initiate the conversation by emitting a "hello .. includecode:: ../code/docs/stream/io/StreamTcpDocSpec.scala#welcome-banner-chat-server To emit the initial message we merge a ``Source`` with a single element, after the command processing but before the -framing and transformation to ``ByteStrings`` this way we do not have to repeat such logic. +framing and transformation to ``ByteString`` s this way we do not have to repeat such logic. In this example both client and server may need to close the stream based on a parsed command - ``BYE`` in the case of the server, and ``q`` in the case of the client. This is implemented by taking from the stream until ``q`` and