Merge pull request #1834 from benjchristensen/toSerializedSubject

Subject.toSerialized

Author: benjchristensen

src/main/java/rx/subjects/Subject.java

@@ -17,6 +17,7 @@
 
 import rx.Observable;
 import rx.Observer;
+import rx.Subscriber;
 
 /**
  * Represents an object that is both an Observable and an Observer.
@@ -31,4 +32,23 @@ protected Subject(OnSubscribe<R> onSubscribe) {
      * @return true if there is at least one Observer subscribed to this Subject, false otherwise
      */
     public abstract boolean hasObservers();
+    
+    /**
+     * Wraps a {@link Subject} so that it is safe to call its various {@code on} methods from different threads.
+     * <p>
+     * When you use an ordinary {@link Subject} as a {@link Subscriber}, you must take care not to call its 
+     * {@link Subscriber#onNext} method (or its other {@code on} methods) from multiple threads, as this could 
+     * lead to non-serialized calls, which violates the Observable contract and creates an ambiguity in the resulting Subject.
+     * <p>
+     * To protect a {@code Subject} from this danger, you can convert it into a {@code SerializedSubject} with code
+     * like the following:
+     * <p><pre>{@code
+     * mySafeSubject = myUnsafeSubject.toSerialized();
+     * }</pre>
+     * 
+     * @return SerializedSubject wrapping the current Subject
+     */
+    public final SerializedSubject<T, R> toSerialized() {
+        return new SerializedSubject<T, R>(this);
+    }
 }