2.x: Document size-bounded replay emission retention caveat (#5827) (#5828)

Author: btilbrook-nextfaze

src/main/java/io/reactivex/Flowable.java

@@ -11234,6 +11234,9 @@ public final <R> Flowable<R> replay(Function<? super Flowable<T>, ? extends Publ
      * emitted by a {@link ConnectableFlowable} that shares a single subscription to the source Publisher,
      * replaying {@code bufferSize} notifications.
      * <p>
+     * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
+     * {@code bufferSize} source emissions.
+     * <p>
      * <img width="640" height="440" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fn.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -11270,6 +11273,9 @@ public final <R> Flowable<R> replay(Function<? super Flowable<T>, ? extends Publ
      * emitted by a {@link ConnectableFlowable} that shares a single subscription to the source Publisher,
      * replaying no more than {@code bufferSize} items that were emitted within a specified time window.
      * <p>
+     * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
+     * {@code bufferSize} source emissions.
+     * <p>
      * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fnt.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -11309,6 +11315,9 @@ public final <R> Flowable<R> replay(Function<? super Flowable<T>, ? extends Publ
      * emitted by a {@link ConnectableFlowable} that shares a single subscription to the source Publisher,
      * replaying no more than {@code bufferSize} items that were emitted within a specified time window.
      * <p>
+     * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
+     * {@code bufferSize} source emissions.
+     * <p>
      * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fnts.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -11357,6 +11366,9 @@ public final <R> Flowable<R> replay(Function<? super Flowable<T>, ? extends Publ
      * emitted by a {@link ConnectableFlowable} that shares a single subscription to the source Publisher,
      * replaying a maximum of {@code bufferSize} items.
      * <p>
+     * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
+     * {@code bufferSize} source emissions.
+     * <p>
      * <img width="640" height="440" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fns.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -11512,6 +11524,9 @@ public final <R> Flowable<R> replay(final Function<? super Flowable<T>, ? extend
      * an ordinary Publisher, except that it does not begin emitting items when it is subscribed to, but only
      * when its {@code connect} method is called.
      * <p>
+     * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
+     * {@code bufferSize} source emissions.
+     * <p>
      * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.n.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -11542,6 +11557,9 @@ public final ConnectableFlowable<T> replay(final int bufferSize) {
      * Publisher resembles an ordinary Publisher, except that it does not begin emitting items when it is
      * subscribed to, but only when its {@code connect} method is called.
      * <p>
+     * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
+     * {@code bufferSize} source emissions.
+     * <p>
      * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.nt.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -11576,6 +11594,9 @@ public final ConnectableFlowable<T> replay(int bufferSize, long time, TimeUnit u
      * Connectable Publisher resembles an ordinary Publisher, except that it does not begin emitting items
      * when it is subscribed to, but only when its {@code connect} method is called.
      * <p>
+     * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
+     * {@code bufferSize} source emissions.
+     * <p>
      * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.nts.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -11618,6 +11639,9 @@ public final ConnectableFlowable<T> replay(final int bufferSize, final long time
      * an ordinary Publisher, except that it does not begin emitting items when it is subscribed to, but only
      * when its {@code connect} method is called.
      * <p>
+     * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
+     * {@code bufferSize} source emissions.
+     * <p>
      * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.ns.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>

src/main/java/io/reactivex/Observable.java

@@ -9498,6 +9498,9 @@ public final <R> Observable<R> replay(Function<? super Observable<T>, ? extends
      * emitted by a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource,
      * replaying {@code bufferSize} notifications.
      * <p>
+     * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
+     * {@code bufferSize} source emissions.
+     * <p>
      * <img width="640" height="391" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.fn.png" alt="">
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
@@ -9529,6 +9532,9 @@ public final <R> Observable<R> replay(Function<? super Observable<T>, ? extends
      * emitted by a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource,
      * replaying no more than {@code bufferSize} items that were emitted within a specified time window.
      * <p>
+     * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
+     * {@code bufferSize} source emissions.
+     * <p>
      * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.fnt.png" alt="">
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
@@ -9563,6 +9569,9 @@ public final <R> Observable<R> replay(Function<? super Observable<T>, ? extends
      * emitted by a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource,
      * replaying no more than {@code bufferSize} items that were emitted within a specified time window.
      * <p>
+     * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
+     * {@code bufferSize} source emissions.
+     * <p>
      * <img width="640" height="328" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.fnts.png" alt="">
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
@@ -9606,6 +9615,9 @@ public final <R> Observable<R> replay(Function<? super Observable<T>, ? extends
      * emitted by a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource,
      * replaying a maximum of {@code bufferSize} items.
      * <p>
+     * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
+     * {@code bufferSize} source emissions.
+     * <p>
      * <img width="640" height="362" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.fns.png" alt="">
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
@@ -9740,6 +9752,9 @@ public final <R> Observable<R> replay(final Function<? super Observable<T>, ? ex
      * an ordinary ObservableSource, except that it does not begin emitting items when it is subscribed to, but only
      * when its {@code connect} method is called.
      * <p>
+     * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
+     * {@code bufferSize} source emissions.
+     * <p>
      * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.n.png" alt="">
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
@@ -9765,6 +9780,9 @@ public final ConnectableObservable<T> replay(final int bufferSize) {
      * ObservableSource resembles an ordinary ObservableSource, except that it does not begin emitting items when it is
      * subscribed to, but only when its {@code connect} method is called.
      * <p>
+     * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
+     * {@code bufferSize} source emissions.
+     * <p>
      * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.nt.png" alt="">
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
@@ -9794,6 +9812,9 @@ public final ConnectableObservable<T> replay(int bufferSize, long time, TimeUnit
      * Connectable ObservableSource resembles an ordinary ObservableSource, except that it does not begin emitting items
      * when it is subscribed to, but only when its {@code connect} method is called.
      * <p>
+     * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
+     * {@code bufferSize} source emissions.
+     * <p>
      * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.nts.png" alt="">
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
@@ -9830,6 +9851,9 @@ public final ConnectableObservable<T> replay(final int bufferSize, final long ti
      * an ordinary ObservableSource, except that it does not begin emitting items when it is subscribed to, but only
      * when its {@code connect} method is called.
      * <p>
+     * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
+     * {@code bufferSize} source emissions.
+     * <p>
      * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.ns.png" alt="">
      * <dl>
      *  <dt><b>Scheduler:</b></dt>

src/main/java/io/reactivex/processors/ReplayProcessor.java

@@ -66,6 +66,10 @@
  * if an individual item gets delayed due to backpressure.
  *
  * <p>
+ * Due to concurrency requirements, a size-bounded {@code ReplayProcessor} may hold strong references to more source
+ * emissions than specified.
+ *
+ * <p>
  * Example usage:
  * <pre> {@code
 

src/main/java/io/reactivex/subjects/ReplaySubject.java

@@ -92,6 +92,9 @@
  * {@link #getThrowable()} and {@link #hasObservers()} as well as means to read the retained/cached items
  * in a non-blocking and thread-safe manner via {@link #hasValue()}, {@link #getValue()},
  * {@link #getValues()} or {@link #getValues(Object[])}.
+ * <p>
+ * Note that due to concurrency requirements, a size-bounded {@code ReplaySubject} may hold strong references to more
+ * source emissions than specified.
  * <dl>
  *  <dt><b>Scheduler:</b></dt>
  *  <dd>{@code ReplaySubject} does not operate by default on a particular {@link io.reactivex.Scheduler} and