Backpressure Fixes and Docs

Docs for operators that don't support backpressure, particularly all the temporal operators.

Fixes for several that needed to request(1) or request(Long.MAX_VALUE).

Author: benjchristensen

rxjava-core/src/main/java/rx/Observable.java

@@ -62,7 +62,12 @@ private IterableProducer(Subscriber<? super T> o, Iterator<? extends T> it) {
 
         @Override
         public void request(long n) {
+            if (REQUESTED_UPDATER.get(this) == Long.MAX_VALUE) {
+                // already started with fast-path
+                return;
+            }
             if (n == Long.MAX_VALUE) {
+                REQUESTED_UPDATER.set(this, n);
                 // fast-path without backpressure
                 while (it.hasNext()) {
                     if (o.isUnsubscribed()) {

rxjava-core/src/main/java/rx/internal/operators/OnSubscribeFromIterable.java

@@ -56,7 +56,12 @@ private RangeProducer(Subscriber<? super Integer> o, int start, int end) {
 
         @Override
         public void request(long n) {
+            if (REQUESTED_UPDATER.get(this) == Long.MAX_VALUE) {
+                // already started with fast-path
+                return;
+            }
             if (n == Long.MAX_VALUE) {
+                REQUESTED_UPDATER.set(this, n);
                 // fast-path without backpressure
                 for (long i = index; i <= end; i++) {
                     if (o.isUnsubscribed()) {

rxjava-core/src/main/java/rx/internal/operators/OnSubscribeRange.java

@@ -45,6 +45,13 @@ public Subscriber<? super T> call(final Subscriber<? super T> child) {
         return new Subscriber<T>(child) {
             final DebounceState<T> state = new DebounceState<T>();
             final Subscriber<?> self = this;
+            
+            @Override
+            public void onStart() {
+                // debounce wants to receive everything as a firehose without backpressure
+                request(Long.MAX_VALUE);
+            }
+            
             @Override
             public void onNext(T t) {
                 Observable<U> debouncer;

rxjava-core/src/main/java/rx/internal/operators/OperatorDebounceWithSelector.java

@@ -44,6 +44,8 @@ public void onNext(T t) {
                 U key = keySelector.call(t);
                 if (keyMemory.add(key)) {
                     child.onNext(t);
+                } else {
+                    request(1);
                 }
             }
 

rxjava-core/src/main/java/rx/internal/operators/OperatorDistinct.java

@@ -45,6 +45,8 @@ public void onNext(T t) {
                 if (hasPrevious) {
                     if (!(currentKey == key || (key != null && key.equals(currentKey)))) {
                         child.onNext(t);
+                    } else {
+                        request(1);
                     }
                 } else {
                     hasPrevious = true;

rxjava-core/src/main/java/rx/internal/operators/OperatorDistinctUntilChanged.java

@@ -55,6 +55,8 @@ public void onNext(T value) {
                 if (currentIndex == index) {
                     subscriber.onNext(value);
                     subscriber.onCompleted();
+                } else {
+                    request(1);
                 }
                 currentIndex++;
             }

rxjava-core/src/main/java/rx/internal/operators/OperatorElementAt.java

@@ -74,6 +74,16 @@ public GroupBySubscriber(Func1<? super T, ? extends K> keySelector, Subscriber<?
         static final AtomicIntegerFieldUpdater<GroupBySubscriber> TERMINATED_UPDATER
                 = AtomicIntegerFieldUpdater.newUpdater(GroupBySubscriber.class, "terminated");
 
+        @Override
+        public void onStart() {
+            /*
+             * This operator does not support backpressure as splitting a stream effectively turns it into a "hot observable" and
+             * blocking any one group would block the entire parent stream. If backpressure is needed on individual groups then
+             * operators such as `onBackpressureDrop` or `onBackpressureBuffer` should be used.
+             */
+            request(Long.MAX_VALUE);
+        }
+        
         @Override
         public void onCompleted() {
             if (TERMINATED_UPDATER.compareAndSet(this, 0, 1)) {

rxjava-core/src/main/java/rx/internal/operators/OperatorGroupBy.java

@@ -70,6 +70,16 @@ public Subscriber<? super T> call(Subscriber<? super GroupedObservable<K, R>> ch
             /** Guarded by guard. */
             Map<K, GroupSubject<K, R>> groups = new HashMap<K, GroupSubject<K, R>>();
 
+            @Override
+            public void onStart() {
+                /*
+                 * This operator does not support backpressure as splitting a stream effectively turns it into a "hot observable" and
+                 * blocking any one group would block the entire parent stream. If backpressure is needed on individual groups then
+                 * operators such as `onBackpressureDrop` or `onBackpressureBuffer` should be used.
+                 */
+                request(Long.MAX_VALUE);
+            }
+            
             final Subscriber<T> self = this;
             @Override
             public void onNext(T t) {

rxjava-core/src/main/java/rx/internal/operators/OperatorGroupByUntil.java

@@ -70,6 +70,12 @@ static final class SamplerSubscriber<T> extends Subscriber<T> implements Action0
         public SamplerSubscriber(Subscriber<? super T> subscriber) {
             this.subscriber = subscriber;
         }
+        
+        @Override
+        public void onStart() {
+            request(Long.MAX_VALUE);
+        }
+        
         @Override
         public void onNext(T t) {
             value = t;