From b971d5672afa29ff6185d9949508cce155518aef Mon Sep 17 00:00:00 2001
From: punitda <punitdama@gmail.com>
Date: Tue, 13 Nov 2018 18:28:56 +0530
Subject: [PATCH] Javadoc : Explain explicitly about non-concurrency for
 Emitter interface methods

---
 src/main/java/io/reactivex/Emitter.java    |  5 +++++
 src/main/java/io/reactivex/Flowable.java   | 25 ++++++++++++++++++++++
 src/main/java/io/reactivex/Observable.java | 25 ++++++++++++++++++++++
 3 files changed, 55 insertions(+)

diff --git a/src/main/java/io/reactivex/Emitter.java b/src/main/java/io/reactivex/Emitter.java
index 2f60f90478..0d95e80dcf 100644
--- a/src/main/java/io/reactivex/Emitter.java
+++ b/src/main/java/io/reactivex/Emitter.java
@@ -17,6 +17,11 @@
 /**
  * Base interface for emitting signals in a push-fashion in various generator-like source
  * operators (create, generate).
+ * <p>
+ * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
+ * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
+ * never concurrently. Calling them from multiple threads is not supported and leads to an
+ * undefined behavior.
  *
  * @param <T> the value type emitted
  */
diff --git a/src/main/java/io/reactivex/Flowable.java b/src/main/java/io/reactivex/Flowable.java
index 666c7c765d..da4f800670 100644
--- a/src/main/java/io/reactivex/Flowable.java
+++ b/src/main/java/io/reactivex/Flowable.java
@@ -2210,6 +2210,11 @@ public static <T> Flowable<T> fromPublisher(final Publisher<? extends T> source)
 
     /**
      * Returns a cold, synchronous, stateless and backpressure-aware generator of values.
+     * <p>
+     * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
+     * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
+     * never concurrently and only while the function body is executing. Calling them from multiple threads
+     * or outside the function call is not supported and leads to an undefined behavior.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>The operator honors downstream backpressure.</dd>
@@ -2236,6 +2241,11 @@ public static <T> Flowable<T> generate(final Consumer<Emitter<T>> generator) {
 
     /**
      * Returns a cold, synchronous, stateful and backpressure-aware generator of values.
+     * <p>
+     * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
+     * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
+     * never concurrently and only while the function body is executing. Calling them from multiple threads
+     * or outside the function call is not supported and leads to an undefined behavior.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>The operator honors downstream backpressure.</dd>
@@ -2263,6 +2273,11 @@ public static <T, S> Flowable<T> generate(Callable<S> initialState, final BiCons
 
     /**
      * Returns a cold, synchronous, stateful and backpressure-aware generator of values.
+     * <p>
+     * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
+     * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
+     * never concurrently and only while the function body is executing. Calling them from multiple threads
+     * or outside the function call is not supported and leads to an undefined behavior.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>The operator honors downstream backpressure.</dd>
@@ -2292,6 +2307,11 @@ public static <T, S> Flowable<T> generate(Callable<S> initialState, final BiCons
 
     /**
      * Returns a cold, synchronous, stateful and backpressure-aware generator of values.
+     * <p>
+     * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
+     * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
+     * never concurrently and only while the function body is executing. Calling them from multiple threads
+     * or outside the function call is not supported and leads to an undefined behavior.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>The operator honors downstream backpressure.</dd>
@@ -2318,6 +2338,11 @@ public static <T, S> Flowable<T> generate(Callable<S> initialState, BiFunction<S
 
     /**
      * Returns a cold, synchronous, stateful and backpressure-aware generator of values.
+     * <p>
+     * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
+     * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
+     * never concurrently and only while the function body is executing. Calling them from multiple threads
+     * or outside the function call is not supported and leads to an undefined behavior.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>The operator honors downstream backpressure.</dd>
diff --git a/src/main/java/io/reactivex/Observable.java b/src/main/java/io/reactivex/Observable.java
index 8ab4059642..c022a0f9fa 100644
--- a/src/main/java/io/reactivex/Observable.java
+++ b/src/main/java/io/reactivex/Observable.java
@@ -1992,6 +1992,11 @@ public static <T> Observable<T> fromPublisher(Publisher<? extends T> publisher)
      * Returns a cold, synchronous and stateless generator of values.
      * <p>
      * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/generate.2.png" alt="">
+     * <p>
+     * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
+     * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
+     * never concurrently and only while the function body is executing. Calling them from multiple threads
+     * or outside the function call is not supported and leads to an undefined behavior.
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code generate} does not operate by default on a particular {@link Scheduler}.</dd>
@@ -2016,6 +2021,11 @@ public static <T> Observable<T> generate(final Consumer<Emitter<T>> generator) {
      * Returns a cold, synchronous and stateful generator of values.
      * <p>
      * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/generate.2.png" alt="">
+     * <p>
+     * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
+     * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
+     * never concurrently and only while the function body is executing. Calling them from multiple threads
+     * or outside the function call is not supported and leads to an undefined behavior.
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code generate} does not operate by default on a particular {@link Scheduler}.</dd>
@@ -2041,6 +2051,11 @@ public static <T, S> Observable<T> generate(Callable<S> initialState, final BiCo
      * Returns a cold, synchronous and stateful generator of values.
      * <p>
      * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/generate.2.png" alt="">
+     * <p>
+     * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
+     * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
+     * never concurrently and only while the function body is executing. Calling them from multiple threads
+     * or outside the function call is not supported and leads to an undefined behavior.
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code generate} does not operate by default on a particular {@link Scheduler}.</dd>
@@ -2071,6 +2086,11 @@ public static <T, S> Observable<T> generate(
      * Returns a cold, synchronous and stateful generator of values.
      * <p>
      * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/generate.2.png" alt="">
+     * <p>
+     * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
+     * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
+     * never concurrently and only while the function body is executing. Calling them from multiple threads
+     * or outside the function call is not supported and leads to an undefined behavior.
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code generate} does not operate by default on a particular {@link Scheduler}.</dd>
@@ -2096,6 +2116,11 @@ public static <T, S> Observable<T> generate(Callable<S> initialState, BiFunction
      * Returns a cold, synchronous and stateful generator of values.
      * <p>
      * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/generate.2.png" alt="">
+     * <p>
+     * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
+     * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
+     * never concurrently and only while the function body is executing. Calling them from multiple threads
+     * or outside the function call is not supported and leads to an undefined behavior.
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code generate} does not operate by default on a particular {@link Scheduler}.</dd>