4.4 Reworked chapter

Author: Froussios

Part 4 - Concurrency/4. Backpressure.md

@@ -1,6 +1,6 @@
 # Backpressure
 
-Rx leads events from the end of a pipeline to another other. The actions that take place on each end can be very dissimilar. What happens when the producer and the consumer require different amounts of time to process a value? In a synchronous model this question isn't an issue. Consider the following example:
+Rx leads events from one end of a pipeline to the other. The actions which take place on each end can be very dissimilar. What happens when the producer and the consumer require different amounts of time to process a value? In a synchronous model, this question isn't an issue. Consider the following example:
 
 ```java
 // Produce
@@ -79,13 +79,13 @@ Output
 
 The are similar operators that can serve the same purpose.
 * The [throttle](/Part 3 - Taming the sequence/5. Time-shifted sequences.md#throttling) family of operators also filters on rate, but allows you to speficy in a diffent way which element to let through when stressed.
-* [Debounce](/Part 3 - Taming the sequence/5. Time-shifted sequences.md#debouncing) does not cut the rate to a fixed maximum. Instead, it will completely remove any burst of information and replace it with a single value.
+* [Debounce](/Part 3 - Taming the sequence/5. Time-shifted sequences.md#debouncing) does not cut the rate to a fixed maximum. Instead, it will completely remove every burst of information and replace it with a single value.
 
 #### Collect
 
-Instead of sampling the data, you can use `buffer` and `window` to collect overflowing data while the consumer is busy. This is useful if processing items in batches is faster. Alternatively, you can decide manually how many and which of the buffered items to process.
+Instead of sampling the data, you can use `buffer` and `window` to collect overflowing data while the consumer is busy. This is useful if processing items in batches is faster. Alternatively, you can inspect the buffer to manually decide how many and which of the buffered items to process.
 
-The example that we saw previously processes multiple items with the same speed that it processes bulks. Here we slowed down the producer to make the batches fit a line, but the principle remains the same.
+In the example that we saw previously, the consumer processes single items and bulks at practically the same speed. Here we slowed down the producer to make the batches fit a line, but the principle remains the same.
 
 ```java
 Observable.interval(10, TimeUnit.MILLISECONDS)
@@ -143,7 +143,7 @@ class MySubscriber extends Subscriber<T> {
 }
 ```
 
-The `request(1)` in `onStart` establishes backpressure and that the observable should only emit the first value. After processing it in `onNext`, we request the next item to be sent, if and when it is available. Calling `request(Long.MAX_VALUE)` would disable backpressure.
+The `request(1)` in `onStart` establishes backpressure and informs the observable that it should only emit the first value. After processing the value in `onNext`, we request the next item to be sent, if and when it is available. Calling `request(Long.MAX_VALUE)` disables backpressure.
 
 ### doOnRequested
 
@@ -153,7 +153,7 @@ public final Observable<T> doOnRequest(Action1<java.lang.Long> onRequest)
 ```
 The `doOnRequested` meta-event happens when a subscriber requests for more items. The value supplied to the action is the number of items requested.
 
-At this moment, `doOnRequest` is in beta. It is the only beta operator that we will discuss in this book. We're making an exception, because it enables us to peek into stable backpressure functionality that is otherwise hidden. Let's see what happens in the most simple observable
+At this moment, `doOnRequest` is in beta. In this book, we have been avoiding beta operators. We're making an exception here, because it enables us to peek into stable backpressure functionality that is otherwise hidden. Let's see what happens in a simple observable:
 
 ```java
 Observable.range(0, 3)
@@ -168,7 +168,7 @@ Requested 9223372036854775807
 2
 ```
 
-We see that `subscribe` requests the maximum number of items from the beginning. That means that `subscribe` doesn't resist values at all. Subscribe will only use backpressure if we provide a subscriber that implements backpressure. Here is a complete example for such an implementation
+We see that `subscribe` requests the maximum number of items from the beginning. This means that `subscribe` doesn't resist values at all. Subscribe will only use backpressure if we provide a subscriber that implements backpressure. Here is a complete example for such an implementation
 
 ```java
 public class ControlledPullSubscriber<T> extends Subscriber<T> {
@@ -245,9 +245,9 @@ Requested 1
 2
 ```
 
-First we requested no emissions. Then we requested 2 and we got 2 values.
+First we requested no emissions (our `ControlledPullSubscriber` does this in `onStart`). Then we requested 2 and we got 2 values, then we requested 1 and we got 1.
 
-Rx operators that use queues and buffers internally should use backpressure to avoid storing an infinite amount of values. Large-scale buffering should be left to operators that explicitly serve this purpose, such as `cache`, `buffer` etc. `zip` is one operator that needs to buffer items: the first observable might emit two or more values before the second observable emits its next value. Such small asymmetries are expected and they shouldn't cause the operator to fail. For that reason, `zip` has a small buffer of 128 items.
+Rx operators that use queues and buffers internally should use backpressure to avoid storing an infinite amount of values. Large-scale buffering should be left to operators that explicitly serve this purpose, such as `cache`, `buffer` etc. An example of an operator that needs to buffer items is `zip`: the first observable might emit two or more values before the second observable emits its next value. Such small asymmetries are expected even when the two sequences are supposed to have the same frequency. Needing to buffer a couple of items shouldn't cause the operator to fail. For that reason, `zip` has a small buffer of 128 items.
 
 ```java
 Observable.range(0, 300)
@@ -266,12 +266,12 @@ Requested 90
 Requested 90
 ```
 
-The `zip` operator starts by requesting enough items to fill its buffer, and requests more when it has consumed enough. The details of how many items `zip` requests isn't interesting. What the reader should take away is the realisation that some buffering and backpressure exist in Rx whether the developer requests for it or not. This gives an Rx pipeline some flexibility where you might expect none. This might trick you into thinking that your code is solid, by silently saving small tests from failing, but you're not safe until you have explicitly declared behaviour with regard to backpressure.
+The `zip` operator starts by requesting enough items to fill its buffer, and requests more when it consumes them. The details of how many items `zip` requests isn't interesting. What the reader should take away is the realisation that some buffering and backpressure exist in Rx whether the developer requests for it or not. This gives an Rx pipeline some flexibility, where you might expect none. It might trick you into thinking that your code is solid, by silently saving small tests from failing, but you're not safe until you have explicitly declared behaviour with regard to backpressure.
 
 
 ## Backpressure policies
 
-Many Rx operators use backpressure internally to avoid overfilling their internal queues. This way, the problem of a slow consumer is propagated backwards in the chain of operators. Backpressure doesn't make the problem go away. It merely moves it where it may be handled better. We still need to decide what to do with the values of an overproducing observable.
+Many Rx operators use backpressure internally to avoid overfilling their internal queues. This way, the problem of a slow consumer is propagated backwards in the chain of operators: if an operator stops accepting values, then the previous operator will fill its buffers until it stops accepting values too, and so on. Backpressure doesn't make the problem go away. It merely moves it where it may be handled better. We still need to decide what to do with the values of an overproducing observable.
 
 There are Rx operators that declare how you want to deal with situations where a subscriber cannot accept the values that are being emitted.
 
@@ -348,7 +348,7 @@ Output
 ...
 ```
 
-What we see here is that the first 128 items where consumed normally, but then we jumped forward. The items inbetween were dropped by `onBackPressureDrop`. Even though we did not request it, the first 128 items where still buffered. Rx employs small buffers even when we don't request it.
+What we see here is that the first 128 items where consumed normally, but then we jumped forward. The items inbetween were dropped by `onBackPressureDrop`. Even though we did not request it, the first 128 items where still buffered, since `observeOn` uses a small buffer between switching threads.
 
 
 | Previous | Next |