Introduction

Replay bounded or unbounded

interface ReplayBuffer<T> {
    void onNext(T value);
    void onError(Throwable e);
    void onCompleted();
    void replay(ReplayProducer<T> child);
}

Unbounded replay buffer

static final class UnboundedReplayBuffer<T> implements ReplayBuffer<T> {
    final List<Object> values = new ArrayList<>();
    volatile int size;
    final NotificationLite<T> nl = NotificationLite.instance();
    @Override
    public void onNext(T value) {
        values.add(nl.next(value));
        size++;
    }
    @Override
    public void onError(Throwable e) {
        values.add(nl.error(e));
        size++;
    }
    @Override
    public void onCompleted() {
        values.add(nl.completed());
        size++;
    }
    @Override
    public void replay(ReplayProducer<T> child) {
        if (child.wip.getAndIncrement() != 0) {
            return;
        }

        int missed = 1;

        for (;;) {

            // implement

            missed = child.wip.addAndGet(-missed);
            if (missed == 0) {
                break;
            }
        }
    }
}

// for (;;)

long r = child.requested.get();
boolean unbounded = r == Long.MAX_VALUE;
long e = 0;
int index = child.index;                    // (1)

while (r != 0L && index != size) {          // (2)
    if (child.isUnsubscribed()) {
        return;
    }

    Object v = values.get(index);           // (3)

    if (nl.accept(child.child, v)) {        // (4)
        return;
    }

    index++;
    r--;
    e--;                                    // (5)
}

if (e != 0L) {
    child.index = index;                    // (6)
    if (!unbounded) {
        child.requested.addAndGet(e);
    }
}
// missed = ...

1. We retrieve the current child requested amount and the current child index. We remember if the request amount was Long.MAX_VALUE and have a counter for emitted values.
2. We have to try emitting if the child can receive it and we haven't reached the end of the available values.
3. If both requests and values are available, we get the next event by index.
4. The NotificationLite.accept will convert the notification object into the proper onXXX call on the child Subscriber and return true if said event is a terminal event.
5. We increment the index, decrement the remaining requested amount and decrement the emission amount. This latter may look strange but it saves us a negation when we update the child requested amount in (6).
6. Finally, if there was any emission, we save the new index and if the child request wasn't unbounded, subtract the emitted count from the child request amount.

Bounded replay buffer

static final class Node {
    final Object value;
    final long id;
    volatile Node next;
    public Node(Object value, long id) {
        this.value = value;
        this.id = id;
    }
}

static final class BoundedReplayBuffer<T>
implements ReplayBuffer<T> {

    final NotificationLite<T> nl = 
            NotificationLite.instance();

    volatile Node head;                            // (1)
    Node tail;
    int size;                                      // (2)
    final int maxSize;
    long id;


    public BoundedReplayBuffer(int maxSize) {      // (3)
        this.maxSize = maxSize;
        tail = new Node(null, 0);
        head = tail;
    }

    void add(Object value) {                       // (4)
        Node n = new Node(value, ++id);
        Node t = tail;
        tail = n;
        t.next = n;
    }

    @Override
    public void onNext(T value) {
        add(nl.next(value));
        if (size == maxSize) {                     // (5)
            Node h = head;
            head = h.next;
        } else {
            size++;
        }
    }

    @Override
    public void onError(Throwable e) {             // (6)
        add(nl.error(e));
    }

    @Override
    public void onCompleted() {
        add(nl.completed());
    }

    @Override
    public void replay(ReplayProducer<T> child) {  // (7)
        if (child.wip.getAndIncrement() != 0) {
            return;
        }

        int missed = 1;

        for (;;) {

            // implement

            missed = child.wip.addAndGet(-missed);
            if (missed == 0) {
                break;
            }
        }
    }
}

1. We have to keep a pointer to the head and tail of the linked node structure. The head has to be volatile because we are going to read it when a child Subscriber subscribes to it; I call this pinning. The tail is only modified from the thread of the main source (already serialized) and is never accessed by the child Subscribers so no need for volatile there.
2. Since we want to limit the number of values to be replayed, we have to know the current size (without walking the linked list all the time) and the maximum allowed count. In addition, we will tag each node with an unique running identifier that will come into play during request coordination.
3. In the constructor, we create our first empty node and assign it to both head and tail. This may seem a bit odd but has its reasons: it allows appending to the end of an empty buffer, otherwise an empty buffer would have null pointers and we'd get a discontinuity. There are two small drawbacks: a) this means the start value at any given time is head.next.value, behind an indirection and b) as we will move the head pointer ahead in (5), it will retain one extra value. In other terms, a replay(5) will keep 6 objects alive. This is true for RxJava's replay() and ReplaySubject too. If one really wants to avoid retaining this extra value, you have to apply reference counting to node which itself adds overhead for every value, both when added to the buffer and when replayed. 
4. We will add new nodes of notifications to the linked list via add. The operation is straightforward: create a new node with a new unique identifier, make it the tail and set the next field of the old tail to this new node. The order is important here because next is volatile and acts as a release operation to all changes made before.
5. Whenever a normal value arrives, we add it to the list and see if we are already at the capacity limit. If not, we can increment the size counter freely. Otherwise, there is no need to change the size anymore as the plus 1 from the add and minus 1 from the remove operation cancels out. This remove operation is basically moving the head forward by one node: given the current head, make the new head the next pointer of the old head. Since the linked structure is guaranteed to have at least one node (due to add()), the new head won't be null and the continuity is preserved.
6. Since the terminal events are (usually) not part of the size bound, we can simply just add their node and not care about trimming the list.
7. Again, the outer drain loop has the well known pattern.

// for (;;) {
long r = child.requested.get();
boolean unbounded = r == Long.MAX_VALUE;
long e = 0;
Node index = child.node;

if (index == null) {                       // (1)
    index = head;
    child.node = index;

    child.addTotalRequested(index.id);     // (2)
}

while (r != 0L && index.next != null) {    // (3)
    if (child.isUnsubscribed()) {
        return;
    }

    Object v = index.value;

    if (nl.accept(child.child, v)) {
        return;
    }

    index = index.next;                    // (4)
    r--;
    e--;
}

if (e != 0L) {
    child.node = index;
    if (unbounded) {
        child.requested.addAndGet(e);
    }
}
// missed = ...

1. Since the nodes are object references, their default is null so the first time the replay is called, we have to capture (pin) the current head of the buffer (and store it in case the requested amount is still zero).
2. The addTotalRequested will get this first node's unique identifier. The reason will be explained in the request coordination section below.
3. To see if we reached the end of the available values, we have to check the next field of index.
4. If the index.next was not null, we have a value for emission and can move the current index ahead by one node.

Request coordination

static final class ReplayProducer<T> 
implements Producer, Subscription {
    int index;
    Node node;                                    // (1)
    final Subscriber<? super T> child;
    final AtomicLong requested;
    final AtomicInteger wip;
    final AtomicLong totalRequested;
    final AtomicBoolean once;                     // (2)

    Connection<T> connection;

    public ReplayProducer(
            Subscriber<? super T> child) {
        this.child = child;
        this.requested = new AtomicLong();
        this.totalRequested = new AtomicLong();
        this.wip = new AtomicInteger();
        this.once = new AtomicBoolean();
    }

    @Override
    public void request(long n) {
        if (n > 0) {
            BackpressureUtils
            .getAndAddRequest(requested, n);
            BackpressureUtils
            .getAndAddRequest(totalRequested, n); // (3)

            connection.manageRequests();          // (4)
        }
    }

    @Override
    public boolean isUnsubscribed() {
        return once.get();
    }

    @Override
    public void unsubscribe() {
        if (once.compareAndSet(false, true)) {
            connection.remove(this);             // (5)
        }
    }

    void addTotalRequested(long n) {             // (6)
        if (n > 0) {
            BackpressureUtils
            .getAndAddRequest(totalRequested, n);
        }
    }
}

1. We want to use the same class for both the bounded and unbounded buffer mode so we have to store the current index/node in fields.
2. We have the usual set of fields: the child Subscriber, the wip counter for the queue-drain serialization, the current requested amount and an AtomicBoolean field indicating an unsubscribed state. In addition we will track the total requested amount and will coordinate requesting from upstream with the help of it.
3. Whenever the child requests, we update both the relative requested amount and the total requested amount with the common BackpressureUtils helper that will cap the amounts at Long.MAX_VALUE if necessary.
4. Once set, we have to trigger a request management to determine if the upstream needs to be requested or not.
5. When the child unsubscribes, we need to remove this ReplayProducer from the array of tracked ReplayProducers.
6. Finally, the bounded buffer's replay requires to update the total requested amount before emission so the request coordination works with latecomers as well.

@SuppressWarnings({ "unchecked", "rawtypes" })
static final class Connection<T> implements Observer<T> {

    final AtomicReference<ReplayProducer<T>[]> subscribers;
    final State<T> state;
    final AtomicBoolean connected;
    final AtomicInteger wip;

    final SourceSubscriber parent;

    final ReplayBuffer<T> buffer;                        // (1)

    static final ReplayProducer[] EMPTY = 
        new ReplayProducer[0];

    static final ReplayProducer[] TERMINATED = 
        new ReplayProducer[0];

    long maxChildRequested;                              // (2)
    long maxUpstreamRequested;

    public Connection(State<T> state, int maxSize) {
        this.state = state;
        this.wip = new AtomicInteger();
        this.subscribers = new AtomicReference<>(EMPTY);
        this.connected = new AtomicBoolean();
        this.parent = createParent();

        ReplayBuffer b;                                 // (3)
        if (maxSize == Integer.MAX_VALUE) {
            b = new UnboundedReplayBuffer<>();
        } else {
            b = new BoundedReplayBuffer<>(maxSize);
        }
        this.buffer = b;
    }

    SourceSubscriber createParent() {                   // (4)
        SourceSubscriber parent = 
            new SourceSubscriber<>(this);

        parent.add(Subscriptions.create(() -> {
            switch (state.strategy) {
            case SEND_COMPLETED:
                onCompleted();
                break;
            case SEND_ERROR:
                onError(new CancellationException(
"Disconnected"));
                break;
            default:
                parent.unsubscribe();
                subscribers.getAndSet(TERMINATED);
            }
        }));

        return parent; 
    }

    boolean add(ReplayProducer<T> producer) {
        // omitted
    }

    void remove(ReplayProducer<T> producer) {
        // omitted 
    }

    void onConnect(
    Action1<? super Subscription> disconnect) {
        // omitted
    }

    @Override
    public void onNext(T t) {                          // (5)
        ReplayBuffer<T> buffer = this.buffer;
        buffer.onNext(t);
        ReplayProducer<T>[] a = subscribers
            .get();
        for (ReplayProducer<T> rp : a) {
            buffer.replay(rp);
        }
    }

    @Override
    public void onError(Throwable e) {
        ReplayBuffer<T> buffer = this.buffer;
        buffer.onError(e);
        ReplayProducer<T>[] a = subscribers
            .getAndSet(TERMINATED);
        for (ReplayProducer<T> rp : a) {
            buffer.replay(rp);
        }
    }

    @Override
    public void onCompleted() {
        ReplayBuffer<T> buffer = this.buffer;
        buffer.onCompleted();
        ReplayProducer<T>[] a = subscribers
            .getAndSet(TERMINATED);
        for (ReplayProducer<T> rp : a) {
            buffer.replay(rp);
        }
    }

    void manageRequests() {                           // (6)
        if (wip.getAndIncrement() != 0) {
            return;
        }

        int missed = 1;

        for (;;) {

            // implement            

            missed = wip.addAndGet(-missed);
            if (missed == 0) {
                break;
            }
        }
    }
}

1. Instead of a bounded queue, we now have the common ReplayBuffer interface.
2. We have to keep track the maximum values of both child requests and requests issued to upstream. The latter is necessary because we can't know when the upstream's Producer arrives and we have to accumulate the coordinated request amount until it arrives.
3. I treat Integer.MAX_VALUE as the indicator for the unbounded replay mode.
4. The createParent is slightly changed. Instead of the disconnected flag, we now unsubscribe directly from upstream. The implementations add, remove and onConnect are the same as in the last post.
5. The onXXX methods have the same pattern: call the appropriate method on the buffer instance and then call replay for all known ReplayProducer instances. Note that the terminal events also swap in the TERMINATED array atomically, indicating that subsequent Subscribers have to go to the next Connection object.
6. Last but not least, we have to manage requests from all child Subscribers which may call the method concurrently and thus we have to do some serialization. Since we are going to calculate the maximum to request, the non-blocking serialization approach works here quite well. This method is called when the upstream producer finally arrives and when any child subscriber requests something.

// for (;;) {

ReplayProducer<T>[] a = subscribers.get();

if (a == TERMINATED) {
    return;
}

long ri = maxChildRequested;
long maxTotalRequests = ri;                 // (1)

for (ReplayProducer<T> rp : a) {
    maxTotalRequests = Math.max(
        maxTotalRequests, 
        rp.totalRequested.get());
}

long ur = maxUpstreamRequested;
Producer p = parent.producer;

long diff = maxTotalRequests - ri;          // (2)
if (diff != 0) {
    maxChildRequested = maxTotalRequests;
    if (p != null) {                        // (3)
        if (ur != 0L) {
            maxUpstreamRequested = 0L;
            p.request(ur + diff);           // (4)
        } else {
            p.request(diff);
        }
    } else {
        long u = ur + diff;
        if (u < 0) {
            u = Long.MAX_VALUE;
        }
        maxUpstreamRequested = u;           // (5)
    }
} else
if (ur != 0L && p != null) {                // (6)
    maxUpstreamRequested = 0L;
    p.request(ur);
}

// missed = ...

1. After retrieving the current array of Subscribers and checking for the disconnected/terminated state, we compute the maximum of the total requested amount of each subscriber (and the previously known maximum).
2. We calculate the difference from the last known maximum. If the difference is non zero, we remember the new maximum in maxChildRequested.
3. At this point, the upstream Producer may be still missing. 
4. If the producer is already there, we take any missed amount and the current difference and request it.
5. Otherwise, without a producer, all we can do is to accumulate all the missed differences.
6. If the maximum didn't change, we still might have to request all missed amounts if the Producer is there. As with (4), we have to "forget" all the missed values thus the next time the requests have to be coordinated, the upstream will only receive the non-zero difference then on.

List<ReplayProducer<T>> coordinationQueue;
boolean coordinateAll;
boolean emitting;
boolean missed;

void manageRequests(ReplayProducer<T> inner) {
    synchronized (this) {                               // (1)
        if (emitting) {
            if (inner != null) {
                List<ReplayProducer<T>> q = 
                    coordinationQueue;
                if (q == null) {
                    q = new ArrayList<>();
                    coordinationQueue = q;
                }
                q.add(inner);
            } else {
                coordinateAll = true;
            }
            missed = true;
            return;
        }
        emitting = true;
    }

    long ri = maxChildRequested;
    long maxTotalRequested;

    if (inner != null) {                                // (2)
        maxTotalRequested = Math.max(
            ri, inner.totalRequested.get());
    } else {
        maxTotalRequested = ri;

        @SuppressWarnings("unchecked")
        ReplayProducer<T>[] a = producers.get();
        for (ReplayProducer<T> rp : a) {
            maxTotalRequested = Math.max(
                maxTotalRequested, rp.totalRequested.get());
        }

    }
    makeRequest(maxTotalRequested, ri);

    for (;;) {
        if (isUnsubscribed()) {
            return;
        }

        List<ReplayProducer<T>> q;
        boolean all;
        synchronized (this) {                           // (3)
            if (!missed) {
                emitting = false;
                return;
            }
            missed = false;
            q = coordinationQueue;
            coordinationQueue = null;
            all = coordinateAll;
            coordinateAll = false;
        }

        ri = maxChildRequested;                         // (4)
        maxTotalRequested = ri;

        if (q != null) {
            for (ReplayProducer<T> rp : q) {
                maxTotalRequested = Math.max(
                maxTotalRequested, rp.totalRequested.get());
            }
        } 

        if (all) {
            @SuppressWarnings("unchecked")
            ReplayProducer<T>[] a = producers.get();
            for (ReplayProducer<T> rp : a) {
                maxTotalRequested = Math.max(
                maxTotalRequested, rp.totalRequested.get());
            }
        }

        makeRequest(maxTotalRequested, ri);
    }
}

1. First, we try to enter the emission loop. If it fails and the parameter to the method was null, we set the coordinateAll flag which will trigger a full sweep. Otherwise, we queue up the ReplayProducer and quit.
2. If the current thread managed to get into the emission state, we either determine the maximum requested by using the single ReplayProducer the method was called with or do a full sweep if it was actually null.
3. Next comes the loop part of the emitter-loop approach. We check if we missed some calls and get all the queued up ReplayProducers as well as the indicator for a full sweep.
4. Given all previous inputs we sweep the queued up ReplayProducers for the maximum value and if necessary, all the other known ReplayProducers as well. Note that they both may have to run since the queue may have ReplayProducers not known at the time this method runs and vice versa.

void makeRequest(long maxTotalRequests, long previousTotalRequests) {
    long ur = maxUpstreamRequested;
    Producer p = producer;

    long diff = maxTotalRequests - previousTotalRequests;
    if (diff != 0) {
        maxChildRequested = maxTotalRequests;
        if (p != null) {
            if (ur != 0L) {
                maxUpstreamRequested = 0L;
                p.request(ur + diff);
            } else {
                p.request(diff);
            }
        } else {
            long u = ur + diff;
            if (u < 0) {
                u = Long.MAX_VALUE;
            }
            maxUpstreamRequested = u;
        }
    } else
    if (ur != 0L && p != null) {
        maxUpstreamRequested = 0L;
        // fire the accumulated requests
        p.request(ur);
    }
}

ReplayConnectableObservable

static final class SourceSubscriber<T> 
extends Subscriber<T> {
    final Connection<T> connection;

    volatile Producer producer;

    public SourceSubscriber(Connection<T> connection) {
        this.connection = connection;
    }

    @Override
    public void onNext(T t) {
        connection.onNext(t);
    }

    @Override
    public void onError(Throwable e) {
        connection.onError(e);
    }

    @Override
    public void onCompleted() {
        connection.onCompleted();
    }

    @Override
    public void setProducer(Producer p) {
        producer = p;
        connection.manageRequests();
    }
}

static final class State<T> implements OnSubscribe<T> {
    final DisconnectStrategy strategy;
    final Observable<T> source;
    final int maxSize;                                     // (1)

    final AtomicReference<Connection<T>> connection;

    public State(DisconnectStrategy strategy, 
    Observable<T> source, int maxSize) {
        this.strategy = strategy;
        this.source = source;
        this.maxSize = maxSize;
        this.connection = new AtomicReference<>(
            new Connection<>(this, maxSize));
    }

    @Override
    public void call(Subscriber<? super T> s) {
        // implement
        ReplayProducer<T> pp = new ReplayProducer<>(s);

        for (;;) {
            Connection<T> curr = this.connection.get();

            pp.connection = curr;

            if (curr.add(pp)) {
                if (pp.isUnsubscribed()) {
                    curr.remove(pp);
                } else {
                    curr.buffer.replay(pp);               // (2)

                    s.add(pp);
                    s.setProducer(pp);
                }

                break;
            }
        }
    }

    public void connect(
    Action1<? super Subscription> disconnect) {
        // same as before
    }

    public void replaceConnection(Connection<T> conn) {   // (3)
        Connection<T> next = 
            new Connection<>(this, maxSize);
        connection.compareAndSet(conn, next);
    }
}

1. We have to store the maxSize parameter because a reconnection has to recreate the appropriate ReplayBuffer instance as well.
2. Once we create an ReplayProducer, first we try to add it to the current connection. If successful, then we do a barebone replay call. Since the ReplayProducer has requested value of zero, this won't replay any value to the child Subscriber. What it does is that it captures the current head of the buffer's linked list (if the buffer is bounded), pins it and makes sure this ReplayProducer starts with the correct total requested amount. Only after this setup is the ReplayProducer added to the child as an unsubscription and request target.
3. Note that the Connection now requires a maxSize parameter.

public static <T> ReplayConnectableObservable<T> createUnbounded(
        Observable<T> source, 
        DisconnectStrategy strategy) {
    return createBounded(source, strategy, Integer.MAX_VALUE);
}

public static <T> ReplayConnectableObservable<T> createBounded(
        Observable<T> source, 
        DisconnectStrategy strategy, int maxSize) {
    State<T> state = new State<>(strategy, source, maxSize);
    return new ReplayConnectableObservable<>(state);
}

Conclusion

Introduction

1. Observe a range of integers from 1 to (1, 1000, 1.000.000) directly.
2. Apply flatMap to the range of integers (1) and transform each value into a single value sequence.
3. Apply flatMap to the range of integers (1) and transform each value into a range of two elements.

• Gradle 2.8
• JMH 1.11.1
• Threads: 1
• Forks: 1
• Mode: Throughput
• Unit: ops/s
• Warmup: 5, 1s each
• Iterations: 5, 2s each
• i7 4790 @ 3.5GHz stock settings CPU
• 16GB DDR3 @ 1600MHz stock RAM
• Windows 7 x64
• Java 8 update 66 x64

RxJava

@Params({"1", "1000", "1000000"})
int times;
//...

Observable<Integer> range = Observable.range(1, times);

Observable<Integer> rangeFlatMapJust = range
    .flatMap(Observable::just);

Observable<Integer> rangeFlatMapRange = range
    .flatMap(v -> Observable.range(v, 2));

public class LatchedObserver<T> extends Observer<T> {
    public CountDownLatch latch = new CountDownLatch(1);
    private final Blackhole bh;
    public LatchedRSObserver(Blackhole bh) {
        this.bh = bh;
    }
    @Override
    public void onComplete() {
        latch.countDown();
    }
    @Override
    public void onError(Throwable e) {
        latch.countDown();
    }
    @Override
    public void onNext(T t) {
        bh.consume(t);
    }
}

@Benchmark
public void range(Blackhole bh) {
    range.subscribe(new LatchedObserver<Integer>(bh));
}

Project Reactor

Stream<Integer> range = Streams.range(1, times);

Stream<Integer> rangeFlatMapJust = raRange.flatMap(Streams::just);

Stream<Integer> rangeFlatMapRange = raRange
    .flatMap(v -> Streams.range(v, 2));

if (maxConcurrency != Integer.MAX_VALUE && !cancelled
&& ++lastRequest == limit) {
    lastRequest = 0;
    subscription.request(limit);
}

• Atomic read and increment is involved which forces the JIT'd code to re-read the instance fields from cache instead of keeping it in a register. The requestConsumer could be read into a local variable before the loop.
• Use == or != as much as possible because the other kind of comparisons appear to be slower on x86.
• The atomic decrement is an expensive operation (~10ns) but can be delayed quite a bit: once the current known requested amount runs out, one should try to read the requested amount first to see if there were more requests issued in the mean time. If so, keep emitting, otherwise subtract all that has been emitted from the request count.

Akka-Streams

List<Integer> values = rx2Range
    .toList().toBlocking().first();

Source.from(values).???

Publisher<Integer> range = Source
    .from(values).runWith(Sink.publisher());

ActorMaterializer materializer = ActorMaterializer
    .create(???);

Publisher<Integer> range = Source.from(values)
    .runWith(Sink.publisher(), materializer);

ActorSystem actorSystem = ActorSystem.create("sys");

ActorMaterializer materializer = ActorMaterializer
    .create(actorSystem);

Publisher<Integer> range = Source.from(values)
    .runWith(Sink.publisher(), materializer);

Config cfg = ConfigFactory.parseResources(
     ReactiveStreamsImpls.class, "/akka-streams.conf");
ActorSystem actorSystem = ActorSystem.create("sys", cfg);

ActorMaterializer materializer = ActorMaterializer
    .create(actorSystem);

List<Integer> values = rx2Range
    .toList().toBlocking().first();

Publisher<Integer> range = Source.from(values)
            .runWith(Sink.publisher(), materializer);

Publisher<Integer> range = s -> Source.from(values)
            .runWith(Sink.publisher(), materializer).subscribe(s);

@Benchmark
public void akRange(Blackhole bh) throws InterruptedException {
    LatchedObserver<Integer> lo = new LatchedObserver<>(bh);
    akRange.subscribe(lo);

    if (times == 1) {
        while (lo.latch.getCount() != 0);
    } else {
        lo.latch.await();
    }
}

Publisher<Integer> rangeFlatMapJust = s -> 
                Source.from(values)
                .map(v -> Source.single(v))
                .flatten(FlattenStrategy.merge())
                .runWith(Sink.publisher(), materializer)
                .subscribe(s)
                ;

FlattenStrategy<Source<Integer, BoxedUnit>> flatten = 
    FlattenStrategy.concat();

Method m = akka.stream.javadsl.FlattenStrategy
    .class.getMethod("concat");

@SuppressWarnings({ "rawtypes", "unchecked" })
FlattenStrategy<Source<Integer, BoxedUnit>, Integer> flatten = 
    (FlattenStrategy)m.invoke(null);

Publisher<Integer> rangeFlatMapJust = s -> 
                Source.from(values)
                .map(v -> Source.single(v))
                .flatten(flatten)
                .runWith(Sink.publisher(), materializer)
                .subscribe(s)
                ;

Plain Java and j.u.c.Stream

@Benchmark
public void javaRange(Blackhole bh) {
    int n = times;
    for (int i = 0; i < n; i++) {
        bh.consume(i);
    }
}

@Benchmark
public void javaRangeFlatMapJust(Blackhole bh) {
    int n = times;
    for (int i = 0; i < n; i++) {
        for (int j = i; j < i + 1; j++) {
            bh.consume(j);
        }
    }
}

@Benchmark
public void javaRangeFlatMapRange(Blackhole bh) {
    int n = times;
    for (int i = 0; i < n; i++) {
        for (int j = i; j < i + 2; j++) {
            bh.consume(j);
        }
    }
}

@Benchmark
public void streamRange(Blackhole bh) {
    values.stream().forEach(bh::consume);
}

@Benchmark
public void streamRangeFlatMapJust(Blackhole bh) {
    values.stream()
    .flatMap(v -> Collections.singletonList(v).stream())
    .forEach(bh::consume);
}

@Benchmark
public void streamRangeFlatMapRange(Blackhole bh) {
    values.stream()
    .flatMap(v -> Arrays.asList(v, v + 1).stream())
    .forEach(bh::consume);
}

@Benchmark
public void pstreamRange(Blackhole bh) {
    values.parallelStream().forEach(bh::consume);
}

@Benchmark
public void pstreamRangeFlatMapJust(Blackhole bh) {
    values.parallelStream()
    .flatMap(v -> Collections.singletonList(v).stream())
    .forEach(bh::consume);
}

@Benchmark
public void pstreamRangeFlatMapRange(Blackhole bh) {
    values.parallelStream()
    .flatMap(v -> Arrays.asList(v, v + 1).stream())
    .forEach(bh::consume);
}

Conclusion

Introduction

The Interfaces

@FunctionalInterface
public interface PushEventSource<T> {
    Closeable open(
        PushEventConsumer<? super T> consumer) throws Exception;
}

• Given a synchronous source, it may be very hard to cancel the connection from within the consumer unless the Closeable is propagated around (more on this later).
• The method throws a checked exception which is generally inconvenient and also seems unnecessary because the exception could be delivered to the consumer.

@FunctionalInterface
public interface PushEventConsumer<T> {
    long ABORT = -1L;
    long CONTINUE = 0L;

    long accept(PushEvent<T> e) throws Exception;
}

• Negative values are considered indication of cancellation or abort.
• Zero indicates the sender can call the method immediately with new data.
• Positive value indicates the sender should wait the specified amount in milliseconds before sending any new data.

• The delay amount is a fixed unit (of milliseconds).
• If the Executor approach is used, it means for each source value, we have a wrapper PushEvent and a Runnable (which is quite an overhead).
• Since the ABORT value is returned synchronously, the cancellation doesn't compose. If we'd implement a library based on this structure and our RxJava lift() approach (in which consumers call other consumers' methods), the moment the accept() call of the downstream consumer has to be called on a different thread, there is no way to get back its result to the original thread:

ExecutorService exec = ...
PushEventOperator<T, T> goAsync = downstreamConsumer -> {
    return e -> {
        exec.execute(() -> {
           long backpressure = downstreamConsumer.accept(e);
        });

        return backpressure; // ???
    };
}; 

public static <T> PushEventSource<T> from(
            Publisher<? extends T> publisher, Scheduler scheduler) {
    return c -> {
        // implement
    };
}

            CompositeDisposable cd = new CompositeDisposable();
            Scheduler.Worker w = scheduler.createWorker();
            cd.add(w);

            publisher.subscribe(new Subscriber<T>() {
                Subscription s;
                @Override
                public void onSubscribe(Subscription s) {
                     // implement
                }

                @Override
                public void onNext(T t) {
                     // implement
                }

                @Override
                public void onError(Throwable t) {
                     // implement
                }

                @Override
                public void onComplete() {
                     // implement
                }

            });

            return cd::dispose;

                @Override
                public void onSubscribe(Subscription s) {
                    this.s = s;
                    cd.add(s::cancel);
                    if (!cd.isDisposed()) {
                        s.request(1);
                    }
                }

                @Override
                public void onNext(T t) {
                    long backpressure;
                    try {
                        backpressure = c.accept(PushEvent.data(t));    // (1)
                    } catch (Exception e) {
                        onError(e);                                    // (2)
                        return;
                    }

                    if (backpressure <= PushEventConsumer.ABORT) {     // (3)
                        cd.dispose();
                    } else
                    if (backpressure == PushEventConsumer.CONTINUE) {  // (4)
                        s.request(1);
                    } else {
                        w.schedule(() -> s.request(1),                 // (5)
                             backpressure, TimeUnit.MILLISECONDS);
                    }
                }

1. We call the accept method and wrap the value into an instance of the aforementioned PushEvent (not detailed here, think of a rx.Notification).
2. In case the accept method throws, we call onError with the exception.
3. Based on the backpressure result being an ABORT value, we dispose the composite and thus cancel the Subscription and dispose the Worker.
4. If the backpressure result is CONTINUE (0), we can synchronously request one more element.
5. Otherwise, we have to schedule the request of a single element after the given number of milliseconds.

                @Override
                public void onError(Throwable t) {
                    cd.dispose();
                    try {
                        c.accept(PushEvent.error(t));
                    } catch (Exception ex) {
                        RxJavaPlugins.onError(ex);
                    }
                }

                @Override
                public void onComplete() {
                    cd.dispose();
                    try {
                        c.accept(PushEvent.close());
                    } catch (Exception ex) {
                        RxJavaPlugins.onError(ex);
                    }

                }

public static <T> Observable<T> to(
        PushEventSource<? extends T> source, long backpressure) {
    return Observable.create(s -> {
        // implement
    });
}

            CompositeDisposable cd = new CompositeDisposable();
            AtomicLong requested = new AtomicLong();

            s.onSubscribe(new Subscription() {
                @Override
                public void request(long n) {
                    BackpressureHelper.add(requested, n);
                }

                @Override
                public void cancel() {
                    cd.dispose();
                }
            });

            try {
                Closeable c = source.open(new PushEventConsumer<T>() {
                    @Override
                    public long accept(PushEvent<T> c) throws Exception {
                        // implement
                    }
                });
                cd.add(() -> {
                    try {
                        c.close();
                    } catch (IOException ex1) {
                        RxJavaPlugins.onError(ex1);
                    }
                });
            } catch (Exception ex2) {
                s.onError(ex2);
            }

    if (cd.isDisposed()) {                           // (1)
        return ABORT;
    }
    switch (c.getType()) {                           // (2)
    case DATA:
        s.onNext(c.getData());
        for (;;) {
            long r = requested.get();                // (3)
            if (r == 0) {
                return backpressure;                 // (4)
            }
            if (requested.compareAndSet(r, r - 1)) {
                return r > 0L ? 0 : backpressure;    // (5)
            }
        }
    case ERROR:                                      // (6)
        cd.dispose();
        s.onError(c.getFailure());
        return ABORT;
    case CLOSE:
        cd.dispose();
        s.onComplete();
        return ABORT;
    }
    return 0L; 

Conclusion

Introduction

What is this Completable class?

Hello World!

Completable.fromAction(() -> System.out.println("Hello World!"))
.subscribe();

public interface CompletableSubscriber {

    void onCompleted();

    void onError(Throwable e);

    void onSubscribe(Subscription d);
}

public interface CompletableOnSubscribe
    extends Action1<CompletableSubscriber> { }

CompletableOnSubscribe complete = cs -> {
    cs.onSubscribe(Subscriptions.unsubscribed());
    cs.onCompleted();
}

public interface CompletableOperator 
    extends Func1<CompletableSubscriber, CompletableSubscriber> { }

CompletableOperator swap = child -> new CompletableSubscriber() {
    @Override
    public void onSubscribe(Subscription s) {
        child.onSubscribe(s);
    }
    @Override
    public void onCompleted() {
        child.onError(new RuntimeException());
    }
    @Override
    public void onError(Throwable e) {
        child.onCompleted();
    }
};

public interface CompletableTransformer
    extends Func1<Completable, Completable> { }

CompletableTransformer schedule = c -> 
    c.subscribeOn(Schedulers.io())
    .observeOn(AndroidSchedulers.mainThread());

Introduction

Empty

Completable empty = Completable.create(completableSubscriber -> {
    BooleanSubscription cancel = new BooleanSubscription();    // (1)

    completableSubscriber.onSubscribe(cancel);                 // (2)

    if (!cancel.isUnsubscribed()) {
        cancel.unsubscribe();                                  // (3)
        completableSubscriber.onCompleted();                   // (4)
    }
});

Completable empty = Completable.create(completableSubscriber -> {
    completableSubscriber.onSubscribe(Subscriptions.unsubscribed());
    completableSubscriber.onCompleted();
});

Empty delayed

public static Completable emptyDelayed(
        long delay, TimeUnit unit, Scheduler scheduler) {
    return Completable.create(cs -> {
        Scheduler.Worker w = scheduler.createWorker();

        cs.onSubscribe(w);

        w.schedule(() -> {
            try {
                cs.onCompleted();
            } finally {
                w.unsubscribe();
            }
        }, delay, unit);
    });
}

Scheduler.Worker w = scheduler.createWorker();

MultipleAssignmentSubscription mas = 
    new MultipleAssignmentSubscription();

mas.set(w);

cs.onSubscribe(mas);

w.schedule(() -> {
    mas.set(Subscriptions.unsubscribed());
    mas.unsubscribe();

    try {
        cs.onCompleted();
    } finally {
        w.unsubscribe();
    }
}, delay, unit);

cs.onSubscribe(
     scheduler.scheduleDirect(cs::onCompleted, delay, unit));

MultipleAssignmentDisposable mad = 
    new MultipleAssignmentDisposable();

cs.onSubscribe(mad);

mad.set(
    scheduler.scheduleDirect(cs::onCompleted, delay, unit));

First completed

public static Completable amb(Completable... students) {
    return Completable.create(principal -> {
        AtomicBoolean done = new AtomicBoolean();            // (1)

        CompositeSubscription all = 
             new CompositeSubscription();                    // (2)

        CompletableSubscriber teacher = 
                new CompletableSubscriber() {
            @Override
            public void onSubscribe(Subscription s) {
                all.add(s);                                  // (3)
            }

            @Override
            public void onCompleted() {
                if (done.compareAndSet(false, true)) {       // (4)
                    all.unsubscribe();
                    principal.onCompleted();
                }
            }

            @Override
            public void onError(Throwable e) {
                if (done.compareAndSet(false, true)) {       // (5)
                    all.unsubscribe();
                    principal.onError(e);
                }
            }
        };

        principal.onSubscribe(all);                          // (6)

        for (Completable student : students) {
            if (done.get() || all.isUnsubscribed()) {        // (7)
                return;
            }
            student.subscribe(teacher);                      // (8)
        }
    });
}

1. We create the shared done indicator which is set to true once one of the student notifies the teacher about its completion (or failure).
2. In case the head principal doesn't like the challenge, he/she can cancel the entire challenge.
3. The teacher will register the Subscriptions given by the student Completables.
4. and makes sure the first who signals the terminal event will also notify the principal about it (unfortunately, he/she won't know who was the first actually). At this point, there is no reason for the others to continue and will be unsubscribed from the challenge.
5. In addition, if it turns out the challenge melts the brain of one of the students, for safety reasons, the challenge has to be cancelled and the head principal notified about the error.
6. We allow the principal to tell each student to stop working on the challenge.
7. For each student Completable, we "hand out" the challenge material and subscribe the teacher to the each students terminal event. It is possible that while the challenge gets completed/failed/cancelled while we are still subscribing to students at which point there is no reason to continue the process.

When all completed

public static Completable merge(Completable... students) {
    return Completable.create(principal -> {
        AtomicInteger remaining = 
            new AtomicInteger(students.length);              // (1)

        CompositeSubscription all = 
            new CompositeSubscription();

        CompletableSubscriber evaluator = 
                 new CompletableSubscriber() {
             @Override
             public void onSubscribe(Subscription s) {
                 all.add(s);
             }

             @Override
             public void onCompleted() {
                 if (remaining.decrementAndGet() == 0) {     // (2)
                     all.unsubscribe();
                     principal.onCompleted();
                 }
             }

             @Override
             public void onError(Throwable e) {
                 if (remaining.getAndSet(0) > 0) {           // (3)
                     all.unsubscribe();
                     principal.onError(e);
                 }
             }
        };

        principal.onSubscribe(all);

        for (Completable student : students) {
            if (all.isUnsubscribed() 
                || remaining.get() <= 0) {                   // (4)
                return;
            }
            student.subscribe(evaluator);
        }
    });

1. We need to count (down) atomically the number of students who completed the evaluation successfully. 
2. Once it reaches zero, the principal is notified about the completion of the entire evaluation.
3. If one of the students signals an error, we set the remaining count to zero atomically and if it was previously non-zero, we cancel everybody and signal the error to the principal. Note that this can happen at most once because if there are multiple concurrent onError calls, only one of them will successfully replace a positive remaining value with a zero value. Any subsequent regular completion will just further decrement the remaining value.
4. If there was an error or cancellation, the loop that subscribes the evaluator to the students should be stopped to not waste more time and resources.

public static Completable mergeDelayError(
        Iterable<? extends Completable> students) {
    return Completable.create(principal -> {
        AtomicInteger wip = new AtomicInteger(1);         // (1)

        CompositeSubscription all = 
            new CompositeSubscription();

        Queue<Throwable> errors = 
            new ConcurrentLinkedQueue<>();                // (2)

        CompletableSubscriber evaluator = 
                new CompletableSubscriber() {
            @Override
            public void onSubscribe(Subscription s) {
                all.add(s);
            }

            @Override
            public void onCompleted() {
                if (wip.decrementAndGet() == 0) {         // (3)
                    if (errors.isEmpty()) {
                        principal.onCompleted();
                    } else {
                        principal.onError(
                            new CompositeException(errors));
                    }
                }
            }

            @Override
            public void onError(Throwable e) {
                errors.offer(e);                          // (4)
                onCompleted();
            }
        };

        principal.onSubscribe(all);

        for (Completable student : students) {
            if (all.isUnsubscribed()) {                   // (5)
                return;
            }
            wip.getAndIncrement();                        // (6)
            student.subscribe(evaluator);
        }

        evaluator.onCompleted();                          // (7)
    });
}

1. We start with an AtomicInteger work-in-progress counter and from number 1. The reason for this is that we don't know how many students are going to get from the Iterable, but we know we have finished once the wip counter reaches zero after all students and the CompletableOnSubscribe finished.
2. We will collect the exceptions into a concurrent queue.
3. The terminal condition is determined in the evaluator's onCompleted method: if the wip counter reaches zero, we check if there were errors queued up along the way and if so, we emit it as a CompositeException. Otherwise, a regular onCompleted event is emitted to the principal.
4. Since we don't stop on error, we have to perform the same wip decrement as in onCompleted, but before that, the error has to be queued up. (Note that misbehaving Completable sources can disrupt this and trigger early completion if they send multiple terminal events.)
5. In the loop where the student Completables are subscribed to we can only check if the principal is no longer interested in the evaluation; the value of the wip counter doesn't help here because it is going to be at least 1 while the loop is running.
6. For each new Completable student, first we increment the wip count and then subscribe the evaluator to it. This makes sure the wip counter is at least 1 so the terminal condition isn't met while the loop is running.
7. Finally, we call the evaluator's onCompleted method to signal no more Completables students will appear. This now allows the wip counter to reach zero and terminate the whole process.

Transformative operators

CompletableOperator onErrorComplete = cs -> {
    return new CompletableSubscriber() {
        @Override
        public void onSubscribe(Subscription s) {
            cs.onSubscribe(s);
        }

        @Override
        public void onCompleted() {
            cs.onCompleted();
        }

        @Override
        public void onError(Throwable e) {
            cs.onCompleted();
        }
    };
};

source.lift(onErrorComplete).subscribe();

public static Completable onErrorResumeNext(
        Completable first,
        Func1<Throwable, ? extends Completable> otherFactory) {

    return first.lift(cs -> new CompletableSubscriber() {
        final SerialSubscription serial = 
            new SerialSubscription();                          // (1)
        boolean once;

        @Override
        public void onSubscribe(Subscription s) {
            serial.set(s);                                     // (2)
        }

        @Override
        public void onCompleted() {
            cs.onCompleted();
        }

        @Override
        public void onError(Throwable e) {
            if (!once) {                                       // (3)
                once = true;
                otherFactory.call(e).subscribe(this);          // (4)
            } else {
                cs.onError(e);                                 // (5)
            }
        }
    });
}

1. Since we may need to switch sources, we have to swap the incoming Subscription from the first to the other Completable. It is possible to use MultipleAssignmentSubscription for this case as well. This is analogous to the ProducerArbiter approach common with Observable operators, although much simpler in nature. In addition, we will reuse the this instance on the new Completable but we don't want to keep resubscribing to it if it fails as well.
2. We set the incoming Subscription on the SerialSubscription, evicting the previous subscription.
3. In case the first signals an error, we make sure the case that switches to the other Completable runs once,
4. because we are going to reuse the current CompletableSubscriber instance for it as well, saving on allocation. The code in (2) makes sure the unsubscription chain is still maintained. This example omits the try-catch around the factory call for brevity; in that case, you can create a CompositeException for both the original error and the fresh crash and call cs.onError with it.
5. If this is the other Completable source that fails, we simply signal the same error downstream.

        // ...
        @Override
        public void onCompleted() {
            if (!once) {                                        // (3)
                once = true;
                otherFactory.call(e).subscribe(this);           // (4)
            } else {
                cs.onCompleted();                               // (5)
            }
        }

        @Override
        public void onError(Throwable e) {
            cs.onError(e);
        }

public static Completable timeout(
        Completable first,
        long timeout, TimeUnit unit, Scheduler scheduler
        Completable other) {
     return first.lift(cs -> new CompletableSubscriber() {

         final CompositeSubscription csub = 
             new CompositeSubscription();                    // (1)

         final AtomicBoolean once = new AtomicBoolean();     // (2)


         @Override
         public void onSubscribe(Subscription s) {
             csub.add(s);                                    // (3)

             Scheduler.Worker w = scheduler.createWorker();
             csub.add(w);

             cs.onSubscribe(csub);

             w.schedule(this::onTimeout, timeout, unit);     // (4)
         }

         @Override
         public void onCompleted() {
             if (once.compareAndSet(false, true)) {
                 csub.unsubscribe();                         // (5)
                 cs.onCompleted();
             }
         }

         @Override
         public void onError(Throwable e) {
             if (once.compareAndSet(false, true)) {
                 csub.unsubscribe();
                 cs.onError(e);
             }
         }

         void onTimeout() {
              if (once.compareAndSet(false, true)) {         // (6)
                  csub.clear();

                  other.subscribe(new CompletableSubscriber() {
                      @Override
                      public void onSubscribe(Subscription s) {
                          csub.add(s);
                      }

                      @Override
                      public void onCompleted() {
                          cs.onCompleted();
                      }

                      @Override
                      public void onError(Throwable e) {
                          cs.onError(e);
                      }
                  });
              }
         }
     });
}

1. We are going to track both the first and other Completable source's Subscription as well as the Worker of the Scheduler that triggers the timeout condition.
2. Since the terminal event of the first Completable races with timeout event, we need to determine a winner (as with amb()) which locks out the other event.
3. When the Subscription arrives from the first source, we add it to the composite, create the Worker and then forward the whole composite to the downstream CompletableSubscriber.
4.  Finally, we schedule the execution of the onTimeout method. This setup avoids the race between the onTimeout and onSubscribe, i.e., if the timeout were scheduled in assembly time, it may happen before the Subscription arrives at which point one needs extra logic to make thinks right (not detailed here). Most of the time, this style of onSubscribe implementation saves a lot of headache with Reactive-Streams compliant operators in 2.0.
5. If the terminal event of the first Completable happens first, we atomically and conditionally set the flag to true (this will prevent the onTimeout to execute its inner logic). Since the composite manages the Worker resource, we have to unsubscribe it, followed by the emission of the original event to downstreams.
6. If the onTimeout happens first and wins the race to set the flag, we clear the composite and subscribe to the other Completable with a fresh CompletableSubscriber. We call clear here because we still need the CompositeSubscription to store the Subscription of the other Completable and an unsubscribed composite is of no use. The additional benefit of clear is that it will cancel the first Completable as well as the Worker running the timeout.

Hot Completable?

public final class CompletableSubject 
extends Completable implements CompletableSubscriber {

    public static CompletableSubject create() {
        State state = new State();
        return new CompletableSubject(state);
    }

    static final class State 
    implements CompletableOnSubscribe, CompletableSubscriber {

        // TODO state fields

        boolean add(CompletableSubscriber t) {
            // TODO implement
        }

        void remove(CompletableSubscriber t) {
            // TODO implement
        }

        @Override
        public void call(CompletableSubscriber t) {
            // TODO implement
        }

        @Override
        public void onSubscribe(Subscription d) {
            // TODO implement
        }

        @Override
        public void onCompleted() {
            // TODO implement

        }

        @Override
        public void onError(Throwable e) {
            // TODO implement

        }
    }

    static final class CompletableSubscription 
    extends AtomicBoolean implements Subscription {
        /** */
        private static final long serialVersionUID = 
            -3940816402954220866L;

        final CompletableSubscriber actual;
        final State state;

        public CompletableSubscription(
                CompletableSubscriber actual, State state) {
            this.actual = actual;
            this.state = state;
        }

        @Override
        public boolean isUnsubscribed() {
            return get();
        }

        @Override
        public void unsubscribe() {
            if (compareAndSet(false, true)) {
                state.remove(this);
            }
        }
    }

    final State state;

    private CompletableSubject(State state) {
        super(state);
        this.state = state;
    }

    @Override
    public void onSubscribe(Subscription d) {
        state.onSubscribe(d);
    }

    @Override
    public void onCompleted() {
        state.onCompleted();
    }

    @Override
    public void onError(Throwable e) {
        state.onError(e);
    }
}

    Throwable error;

    volatile CompletableSubscription[] subscribers = EMPTY;

    static final CompletableSubscription[] EMPTY = 
            new CompletableSubscription[0];
    static final CompletableSubscription[] TERMINATED =
            new CompletableSubscription[0];

    boolean add(CompletableSubscription t) {
        if (subscribers == TERMINATED) {
            return false;
        }
        synchronized (this) {
            CompletableSubscription[] a = subscribers;
            if (a == TERMINATED) {
                return false;
            }

            CompletableSubscription[] b = 
                new CompletableSubscription[a.length + 1];
            System.arraycopy(a, 0, b, 0, a.length);
            b[a.length] = t;
            subscribers = b;
            return true;
        }
    }

    void remove(CompletableSubscription t) {
        CompletableSubscription[] a = subscribers;
        if (a == EMPTY || a == TERMINATED) {
            return;
        }

        synchronized (this) {
            a = subscribers;
            if (a == EMPTY || a == TERMINATED) {
                return;
            }

            int j = -1;
            for (int i = 0; i < a.length; i++) {
                if (a[i] == t) {
                    j = i;
                    break;
                }
            }

            if (j < 0) {
                return;
            }
            if (a.length == 1) {
                subscribers = EMPTY;
                return;
            }
            CompletableSubscription[] b = 
                new CompletableSubscription[a.length - 1];
            System.arraycopy(a, 0, b, 0, j);
            System.arraycopy(a, j + 1, b, j, a.length - j - 1);
            subscribers = b;
        }
    }

    @Override
    public void call(CompletableSubscriber t) {
        CompletableSubscription cs = 
            new CompletableSubscription(t, this);
        t.onSubscribe(cs);

        if (add(cs)) {
            if (cs.isUnsubscribed()) {
                remove(cs);
            }
        } else {
            Throwable e = error;
            if (e != null) {
                t.onError(e);
            } else {
                t.onCompleted();
            }
        }
    }

    @Override
    public void onSubscribe(Subscription d) {
        if (subscribers == TERMINATED) {
            d.unsubscribe();
        }
    }

    @Override
    public void onCompleted() {
        CompletableSubscription[] a;
        synchronized (this) {
            a = subscribers;
            subscribers = TERMINATED;
        }

        for (CompletableSubscription cs : a) {
            cs.actual.onCompleted();
        }
    }

    @Override
    public void onError(Throwable e) {
        CompletableSubscription[] a;
        synchronized (this) {
            a = subscribers;
            error = e;
            subscribers = TERMINATED;
        }

        for (CompletableSubscription cs : a) {
            cs.actual.onError(e);
        }
    }

Introduction

Func1<T, Observable<R>> f = ...
source.flatMap(f) == Observable.merge(source.map(f))


Observable<Observable<R>> o = ...
Observable.merge(o) == o.flatMap(v -> v)

Observable.range(1, 10).flatMap(v -> Observable.range(v, 2))
.subscribe(System.out::println);

Observable.range(1, 10)
.flatMap(v -> Observable.just(v).delay(11 - v, TimeUnit.SECONDS))
.toBlocking()
.subscribe(System.out::println);

Observable.range(1, 10)
.flatMap(v -> {
    if (v < 5) {
        return Observable.just(v * v);
    }
    return Observable.<Integer>error(new IOException("Why not?!"));
})
.subscribe(System.out::println, Throwable::printStackTrace);

Implementing FlatMap

public final class OpFlatMap<T, R> implements Operator<R, T> {

    final Func1<? super T, ? extends Observable<? extends R>> mapper;

    final int prefetch;

    public OpFlatMap(Func1<? super T, ? extends Observable<? extends R>> mapper,
            int prefetch) {
        this.mapper = mapper;
        this.prefetch = prefetch;
    }

    @Override
    public Subscriber call(Subscriber<? super R> t) {
        FlatMapSubscriber<T, R> parent = new FlatMapSubscriber<>(t, mapper, prefetch);
        parent.init();
        return parent;
    }
}

static final class FlatMapSubscriber<T, R> extends Subscriber<T> {
    final Subscriber<? super R> actual;

    final Func1<? super T, ? extends Observable<? extends R>> mapper;

    final int prefetch;                                             // (1)

    final CompositeSubscription csub;                               // (2)

    final AtomicInteger wip;                                        // (3)

    final Queue<Object> queue;                                      // (4)

    final AtomicLong requested;                                     // (5)

    final AtomicInteger active;                                     // (6)

    final AtomicReference<Throwable> error;                         // (7)

    public FlatMapSubscriber(Subscriber<? super R> actual,
            Func1<? super T, ? extends Observable<? extends R>> mapper,
            int prefetch) {
        this.actual = actual;
        this.mapper = mapper;
        this.prefetch = prefetch;
        this.csub = new CompositeSubscription();
        this.wip = new AtomicInteger();
        this.requested = new AtomicLong();
        this.queue = new ConcurrentLinkedQueue<>();
        this.active = new AtomicInteger(1);
        this.error = new AtomicReference<>();
    }

    public void init() {
        // TODO implement
    }

    @Override
    public void onNext(T t) {
        // TODO implement
    }

    @Override
    public void onError(Throwable e) {
        // TODO implement
    }

    @Override
    public void onCompleted() {
        // TODO implement
    }

    void childRequested(long n) {
        // TODO implement
    }

    void innerNext(Subscriber<R> inner, R value) {
        // TODO implement
    }

    void innerError(Throwable ex) {
        // TODO implement
    }

    void innerComplete(Subscriber<?> inner) {
        // TODO implement
    }

    void drain() {
        // TODO implement
    }
}

1. We have the child subscriber, the mapper function and the prefetch value.
2. We will track the inner subscribers with a CompositeSubscription so when the child unsubscribes, we can unsubscribe them all at once, plus when an inner Observable terminates, we can remove just its subscriber.
3. We have the usual work-in-progress atomic integer indicating if there is a drain going on, thus establishing the non-blocking queue-drain approach
4. We have a shared queue where all sources will submit their value before attempting to drain it towards the child subscriber. The queue takes Object instead of R because we will also use this queue to post the Subscriber who generated that particular value so we can request more from that particular source.
5. We need to track the child requested amount because when a child request 1, we can't really tell which inner Observable to request that 1 from, thus we have to request all of them. However, this may yield any number of response items and we can't just simply emit all of them to the child subscriber (possibly causing MissingBackpressureException down the line).
6. We need to track how many active sources there are, including the main source of Ts. When this counter reaches zero, the child subscriber can be completed.
7. Any of the sources may signal an error or even the main source itself as well. For simplicity, we will only store the very first exception and route the rest to the RxJavaPlugins' error handler.

static final class FlatMapInnerSubscriber<T, R> extends Subscriber<R> {
    final FlatMapSubscriber<T, R> parent;

    public FlatMapInnerSubscriber(FlatMapSubscriber<T, R> parent, int prefetch) {
        this.parent = parent;
        request(prefetch);                                         // (1)
    }

    @Override
    public void onNext(R t) {
        parent.innerNext(this, t);                                 // (2)
    }

    @Override
    public void onError(Throwable e) {
        parent.innerError(e);
    }

    @Override
    public void onCompleted() {
        parent.innerComplete(this);
    }

    void requestMore(long n) {
        request(n);                                                // (3)
    }
}

    public void init() {
        add(csub);
        actual.add(this);
        actual.setProducer(new Producer() {
            @Override
            public void request(long n) {
                childRequested(n);
            }
        });
    }

    @Override
    public void onNext(T t) {
        Observable<? extends R> o;

        try {
            o = mapper.call(t);
        } catch (Throwable ex) {
            Exceptions.throwOrReport(ex, this, t);
            return;
        }

        active.getAndIncrement();
        FlatMapInnerSubscriber<T, R> inner = 
                new FlatMapInnerSubscriber<>(this, prefetch);
        csub.add(inner);

        o.subscribe(inner);
    }

    @Override
    public void onError(Throwable e) {
        if (error.compareAndSet(null, e)) {
            unsubscribe();
            drain();
        } else {
            RxJavaPlugins.getInstance()
            .getErrorHandler().handleError(e);
        }
    }

    @Override
    public void onCompleted() {
        if (active.decrementAndGet() == 0) {
            drain();
        }
    }

    AtomicBoolean once = new AtomicBoolean();
    // ...
    @Override
    public void onCompleted() {
        if (once.compareAndSet(false, true)) {
            if (active.decrementAndGet() == 0) {
                drain();
            }
        }
    }

    void childRequested(long n) {
        if (n > 0) {
            BackpressureUtils.getAndAddRequest(requested, n);
            drain();
        }
    }

    void innerNext(Subscriber inner, R value) {
        queue.offer(inner);
        queue.offer(NotificationLite.instance().next(value));
        drain();
    }

    void innerError(Throwable ex) {
        onError(ex);
    }

    void innerComplete(Subscriber inner) {
        csub.remove(inner);
        onCompleted();
    }

if (wip.getAndIncrement() != 0) {
    return;
}

int missed = 1;

for (;;) {

    long r = requested.get();
    long e = 0L;

    while (e != r) {

        if (actual.isUnsubscribed()) {
            return;
        }

        boolean done = active.get() == 0;              // (1)
        Throwable ex = error.get();                    // (2)
        if (ex != null) {
            actual.onError(ex);
            return;
        }

        Object o = queue.poll();

        if (done && o == null) {                       // (3)
            actual.onCompleted();
            return;
        }

        if (o == null) {
            break;
        }

        Object v;

        for (;;) {                                     // (4)
            if (actual.isUnsubscribed()) {
                return;
            }
            v = queue.poll();
            if (v != null) {
                break;
            }
        }

        actual.onNext(NotificationLite
                .<R>instance().getValue(v));           // (5)

        ((FlatMapInnerSubscriber<?, ?>)o)
            .requestMore(1);

        e++;
    }

1. The inside of the drain loop should look familiar with the exception of a secondary loop perhaps. In the while loop, we detect the completion by checking the active count against zero
2. as well as see if the error reference holds something non-null. 
3. Since we put 2 objects inside the queue, we have to take 2 objects out. If the first poll returns null, the queue is empty and if at the same time, done is true, we reached the end of all sources and can complete the child. 
4. However, we can't just poll again because it is possible that the thread got interrupted between the two offer() call in the innerNext() above and thus the second value, the value to be emitted, isn't there yet. Therefore, we need to have an inner loop that keeps polling until the second value arrives (or the child unsubscribes). (Note that this can be avoided with specialized queues or with tuple types.)
5. Once we have the second and real value, we unwrap it - with the help of NotificationLite - and emit it to the child subscriber. At the same time, we cast the sender back to FlatMapInnerSubscriber (of any) and ask for replenishment. The loop body ends by incrementing the emission amount so we can detect if we fulfilled all current requests.

    if (e == r) {
        if (actual.isUnsubscribed()) {
            return;
        }
        boolean done = active.get() == 0;
        Throwable ex = error.get();
        if (ex != null) {
            actual.onError(ex);
            return;
        }

        if (done && queue.isEmpty()) {
            actual.onCompleted();
            return;
        }
    }

    if (e != 0L) {
        BackpressureUtils.produced(requested, e);
    }

    missed = wip.addAndGet(-missed);
    if (missed == 0) {
        break;
    }
}

Conclusion

Introduction

Limiting concurrency

    final int maxConcurrency;

    public OpFlatMap(Func1<? super T, ? extends Observable<? extends R>> mapper,
            int prefetch, int maxConcurrency) {
        this.mapper = mapper;
        this.prefetch = prefetch;
        this.maxConcurrency = maxConcurrency;
    }

    @Override
    public Subscriber<T> call(Subscriber<? super R> t) {
        FlatMapSubscriber<T, R> parent = 
            new FlatMapSubscriber<>(t, mapper, prefetch, maxConcurrency);
        parent.init();
        return parent;
    }

        final int maxConcurrency;

        public FlatMapSubscriber(Subscriber<? super R> actual,
                Func1<? super T, ? extends Observable<? extends R>> mapper,
                int prefetch, int maxConcurrency) {
            this.actual = actual;
            this.mapper = mapper;
            this.prefetch = prefetch;
            this.csub = new CompositeSubscription();
            this.wip = new AtomicInteger();
            this.requested = new AtomicLong();
            this.queue = new ConcurrentLinkedQueue<>();
            this.active = new AtomicInteger(1);
            this.error = new AtomicReference<>();

            this.maxConcurrency = maxConcurrency;
            if (maxConcurrency != Integer.MAX_VALUE) {
                request(maxConcurrency);
            }
        }

        void innerComplete(Subscriber<?> inner) {
            csub.remove(inner);

            request(1);

            onCompleted();
        }

Delaying errors

    final boolean delayErrors;

    public OpFlatMap(Func1<? super T, ? extends Observable<? extends R>> mapper,
            int prefetch, int maxConcurrency, boolean delayErrors) {
        this.mapper = mapper;
        this.prefetch = prefetch;
        this.maxConcurrency = maxConcurrency;
        this.delayErrors = delayErrors;
    }

    @Override
    public Subscriber<T> call(Subscriber<? super R> t) {
        FlatMapSubscriber<T, R> parent = 
            new FlatMapSubscriber<>(t, mapper, prefetch, maxConcurrency, delayErrors);
        parent.init();
        return parent;
    }

    // ...

        final boolean delayErrors;

        public FlatMapSubscriber(Subscriber<? super R> actual,
                Func1<? super T, ? extends Observable<? extends R>> mapper,
                int prefetch, int maxConcurrency, boolean delayErrors) {
            this.actual = actual;
            this.mapper = mapper;
            this.prefetch = prefetch;
            this.csub = new CompositeSubscription();
            this.wip = new AtomicInteger();
            this.requested = new AtomicLong();
            this.queue = new ConcurrentLinkedQueue<>();
            this.active = new AtomicInteger(1);
            this.error = new AtomicReference<>();

            this.maxConcurrency = maxConcurrency;
            if (maxConcurrency != Integer.MAX_VALUE) {
                request(maxConcurrency);
            }

            this.delayErrors = delayErrors;
        }

        @Override
        public void onError(Throwable e) {
            if (delayErrors) {
                for (;;) {
                    Throwable current = error.get();
                    Throwable next;
                    if (current == null) {
                        next = e;
                    } else {
                        List<Throwable> list = new ArrayList<>();
                        if (current instanceof CompositeException) {
                            list.addAll(((CompositeException)current).getExceptions());
                        } else {
                            list.add(current);
                        }
                        list.add(e);

                        next = new CompositeException(list);
                    }

                    if (error.compareAndSet(current, next)) {
                        if (active.decrementAndGet() == 0) {
                            drain();
                        }                        
                        return;
                    }
                }
            } else {
                if (error.compareAndSet(null, e)) {
                    unsubscribe();
                    drain();
                } else {
                    RxJavaPlugins.getInstance()
                    .getErrorHandler().handleError(e);
                }
            }
        }

        void innerError(Throwable ex, Subscriber<?> inner) {
            if (delayErrors) {
                csub.remove(inner);
                request(1);
            }
            onError(ex);
        }

                    boolean done = active.get() == 0;
                    if (!delayErrors) {
                        Throwable ex = error.get();
                        if (ex != null) {
                            actual.onError(ex);
                            return;
                        }
                    }

                    Object o = queue.poll();

                    if (done && o == null) {
                        Throwable ex = error.get();
                        if (ex != null) {
                            actual.onError(ex);
                        } else {
                            actual.onCompleted();
                        }
                        return;
                    }

                    if (o == null) {
                        break;
                    }

                if (e == r) {
                    if (actual.isUnsubscribed()) {
                        return;
                    }
                    boolean done = active.get() == 0;

                    if (!delayErrors) {
                        Throwable ex = error.get();
                        if (ex != null) {
                            actual.onError(ex);
                            return;
                        }
                    }

                    if (done && queue.isEmpty()) {
                        Throwable ex = error.get();
                        if (ex != null) {
                            actual.onError(ex);
                        } else {
                            actual.onCompleted();
                        }
                        return;
                    }
                }

Increasing the performance of the Queue

        void innerNext(FlatMapInnerSubscriber<T, R> inner, R value) {
            Object v = NotificationLite.instance().next(value);    // (1)

            if (wip.get() == 0 && wip.compareAndSet(0, 1)) {       // (2)
                if (requested.get() != 0L) {                       // (3)
                    actual.onNext(value);                          // (4)
                    BackpressureUtils.produced(requested, 1);
                    inner.requestMore(1);
                } else {
                    queue.offer(inner);                            // (5)
                    queue.offer(v);
                }

                if (wip.decrementAndGet() != 0) {                  // (6)
                    drainLoop();
                }
                return;
            }

            queue.offer(inner);                                    // (7)
            queue.offer(v);
            drain();
        }

        void drain() {
            if (wip.getAndIncrement() != 0) {
                return;
            }
            drainLoop();
        }

        void drainLoop() {
            int missed = 1;
            // ...

1. First, we convert the potential null value as it will be potentially required at two places later on.
2. If the wip value is zero and can be successfully changed to 1, we enter into the serialized drain mode and are now free to emit ...
3. if the requested amount is non-zero.
4. Therefore, if there is no contention and there is request from downstream, we emit and don't touch the queue. Once emitted, we have to reduce the requested amount by 1 and request replenishment from the source.
5. If the downstream hasn't requested, we have to revert to the original queuing behavior and store the value for later use.
6. In the drain mode, we decrement the wip counter and if more work has arrived in the meantime, we resume with the loop-part of the former drain. This also means the drain() method has to be refactored into drain() and drainLoop() methods. Using the original drain() here wouldn't work because it would skip its loop due to wip being non-zero already.
7. In case there was a contention, i.e., wip was non-zero, we have to revert to the original queue-drain behavior.

Increasing performance in high-contention case

    static final class FlatMapInnerSubscriber<T, R> extends Subscriber<R> {
        final FlatMapSubscriber<T, R> parent;

        final int prefetch;

        volatile Queue<Object> queue;

        volatile boolean done;

        public FlatMapInnerSubscriber(
                FlatMapSubscriber<T, R> parent, int prefetch) {
            this.parent = parent;
            this.prefetch = prefetch;
            request(prefetch);
        }

        @Override
        public void onNext(R t) {
            parent.innerNext(this, t);
        }

        @Override
        public void onError(Throwable e) {
            done = true;
            parent.innerError(e, this);
        }

        @Override
        public void onCompleted() {
            done = true;
            parent.innerComplete(this);
        }

        void requestMore(long n) {
            request(n);
        }

        Queue<Object> getOrCreateQueue() {
            Queue<Object> q = queue;
            if (q == null) {
                q = new SpscArrayQueue<>(prefetch);
                queue = q;
            }
            return q;
        }
    }

        void innerNext(FlatMapInnerSubscriber<T, R> inner, R value) {
            Object v = NotificationLite.instance().next(value);

            if (wip.get() == 0 && wip.compareAndSet(0, 1)) {
                if (requested.get() != 0L) {
                    actual.onNext(value);
                    BackpressureUtils.produced(requested, 1);
                    inner.requestMore(1);
                } else {

                    Queue<Object> q = inner.getOrCreateQueue();


                    q.offer(v);
                }

                if (wip.decrementAndGet() != 0) {
                    drainLoop();
                }
                return;
            }

            Queue<Object> q = inner.getOrCreateQueue();


            q.offer(v);
            drain();
        }

        @SuppressWarnings("rawtypes")
        static final FlatMapInnerSubscriber[] EMPTY = new FlatMapInnerSubscriber[0];
        @SuppressWarnings("rawtypes")
        static final FlatMapInnerSubscriber[] TERMINATED = new FlatMapInnerSubscriber[0];

        final AtomicReference<FlatMapInnerSubscriber<T, R>[]> subscribers;

        volatile boolean done;

        @SuppressWarnings("unchecked")
        public FlatMapSubscriber(Subscriber<? super R> actual,
                Func1<? super T, ? extends Observable<? extends R>> mapper,
                int prefetch, int maxConcurrency, boolean delayErrors) {
            this.actual = actual;
            this.mapper = mapper;
            this.prefetch = prefetch;
            this.wip = new AtomicInteger();
            this.requested = new AtomicLong();
            this.error = new AtomicReference<>();

            this.subscribers = new AtomicReference<>(EMPTY);

            this.maxConcurrency = maxConcurrency;
            if (maxConcurrency != Integer.MAX_VALUE) {
                request(maxConcurrency);
            }
            this.delayErrors = delayErrors;
        }

        public void init() {
            add(Subscriptions.create(this::terminate));
            actual.add(this);
            actual.setProducer(new Producer() {
                @Override
                public void request(long n) {
                    childRequested(n);
                }
            });
        }

        @SuppressWarnings("unchecked")
        void terminate() {
            FlatMapInnerSubscriber<T, R>[] a = subscribers.get();
            if (a != TERMINATED) {
                a = subscribers.getAndSet(TERMINATED);
                if (a != TERMINATED) {
                    for (FlatMapInnerSubscriber<T, R> inner : a) {
                        inner.unsubscribe();
                    }
                }
            }
        }

        boolean add(FlatMapInnerSubscriber<T, R> inner) {
            for (;;) {
                FlatMapInnerSubscriber<T, R>[] a = subscribers.get();
                if (a == TERMINATED) {
                    return false;
                }
                int n = a.length;
                @SuppressWarnings("unchecked")
                FlatMapInnerSubscriber<T, R>[] b = new FlatMapInnerSubscriber[n + 1];
                System.arraycopy(a, 0, b, 0, n);
                b[n] = inner;
                if (subscribers.compareAndSet(a, b)) {
                    return true;
                }
            }
        }

        @SuppressWarnings("unchecked")
        void remove(FlatMapInnerSubscriber<T, R> inner) {
            for (;;) {
                FlatMapInnerSubscriber<T, R>[] a = subscribers.get();
                if (a == TERMINATED || a == EMPTY) {
                    return;
                }
                int n = a.length;
                int j = -1;
                for (int i = 0; i < n; i++) {
                    if (a[i] == inner) {
                        j = i;
                        break;
                    }
                }

                if (j < 0) {
                    return;
                }

                FlatMapInnerSubscriber<T, R>[] b;
                if (n == 1) {
                    b = EMPTY;
                } else {
                    b = new FlatMapInnerSubscriber[n - 1];
                    System.arraycopy(a, 0, b, 0, j);
                    System.arraycopy(a, j + 1, b, j, n - j - 1);
                }
                if (subscribers.compareAndSet(a, b)) {
                    return;
                }
            }
        }

        @Override
        public void onNext(T t) {
            Observable<? extends R> o;

            try {
                o = mapper.call(t);
            } catch (Throwable ex) {
                Exceptions.throwOrReport(ex, this, t);
                return;
            }

            FlatMapInnerSubscriber<T, R> inner = 
                    new FlatMapInnerSubscriber<>(this, prefetch);

            if (add(inner)) {
                o.subscribe(inner);
            }
        }

                    if (error.compareAndSet(current, next)) {
                        drain();
                        return;
                    }

        @Override
        public void onCompleted() {
            done = true;
            drain();
        }

        void innerError(Throwable ex, FlatMapInnerSubscriber<T, R> inner) {
            onError(ex);
        }

        void innerComplete(FlatMapInnerSubscriber<T, R> inner) {
            drain();
        }

        void drainLoop() {

            int missed = 1;

            for (;;) {
                boolean d = done;

                FlatMapInnerSubscriber<T, R>[] a = subscribers.get();

                long r = requested.get();
                long e = 0L;
                int requestMain = 0;
                boolean again = false;

                if (isUnsubscribed()) {
                    return;
                }

                if (!delayErrors) {
                    Throwable ex = error.get();
                    if (ex != null) {
                        actual.onError(ex);
                        return;
                    }
                }

                if (d && a.length == 0) {
                    Throwable ex = error.get();
                    if (ex != null) {
                        actual.onError(ex);
                    } else {
                        actual.onCompleted();
                    }
                    return;
                }

                for (FlatMapInnerSubscriber<T, R> inner : a) {
                    if (isUnsubscribed()) {
                        return;
                    }

                    d = inner.done;
                    Queue<Object> q = inner.queue;
                    if (q == null) {
                        if (d) {
                            remove(inner);
                            requestMain++;
                            again = true;
                        }
                    } else {

                        long f = 0L;

                        while (e != r) {
                            if (isUnsubscribed()) {
                                return;
                            }

                            d = inner.done;
                            Object v = q.poll();
                            boolean empty = v == null;

                            if (d && empty) {
                                remove(inner);
                                requestMain++;
                                again = true;
                            }

                            if (empty) {
                                break;
                            }

                            actual.onNext(NotificationLite.<R>instance().getValue(v));

                            e++;
                            f++;
                        }

                        if (f != 0L) {
                            inner.requestMore(f);
                        }

                        if (e == r) {
                            if (inner.done && q.isEmpty()) {
                                remove(inner);
                                requestMain++;
                                again = true;
                            }
                            break;
                        }

                    }
                }

                if (e != 0L) {
                    BackpressureUtils.produced(requested, e);
                }
                if (requestMain != 0) {
                    request(requestMain);
                }

                if (again) {
                    continue;
                }

                missed = wip.addAndGet(-missed);
                if (missed == 0) {
                    break;
                }
            }
        }
    }

Inner request rebatching

        final int limit;

        long produced;

        public FlatMapInnerSubscriber(
                FlatMapSubscriber<T, R> parent, int prefetch) {
            this.parent = parent;
            this.prefetch = prefetch;

            this.limit = prefetch - (prefetch >> 2);

            request(prefetch);
        }

        void requestMore(long n) {
            long p = produced + n;
            if (p >= limit) {
                produced = 0;
                request(p);
            } else {
                produced = p;
            }
        }

Conclusion

Intoduction

Synchronous unsubscription

interface IDisposable {
    void dispose();
}

interface IObserver<T> {
   void onNext(T t);
}
interface IObservable<T> {
    IDisposable subscribe(IObserver<T> observer);
}  


IObservable<Integer> source = o -> {
   for (int i = 0; i < Integer.MAX_VALUE; i++) {
       o.onNext(i);
   }

   return () -> { };
};

IDisposable d = o.subscribe(System.out::println);
d.dispose();

Observable<Integer> source = Observable.create(s -> {
   for (int i = 0; i < Integer.MAX_VALUE && !s.isUnsubscribed(); i++) {
       o.onNext(i);
   }
});

Subscription d = o.subscribe(new Subscriber<Integer>() {
    @Override
    public void onNext(Integer v) {
        System.out.println(v);
        unsubscribe();
    }

    // ...
});

Subscriber<Integer> s = new Subscriber<Integer>() {
    @Override
    public void onNext(Integer v) {
        System.out.println();
    }
    // ...
}

Schedulers.computation().schedule(s::unsubscribe, 1, TimeUnit.SECONDS);

source.subscribe(s);

Resources of the Subscriber

Subscriber request

Lift

public final <R> Observable<R> map(Func1<? super T, ? extends R> func) {
    OperatorMap<T, R> op = new OperatorMap<T, R>(func);
    return new Observable<R>(new OnSubscribe<R>() {
        @Override
        public void call(Subscriber<? super R> child) {
            Subscriber<? super T> parent = op.call(child);
            Observable.this.unsafeSubscribe(parent);
        }
    });
}

Observable.range(1, 1_000_000).flatMap(v -> 
    Observable.just(v).observeOn(Schedulers.computation()).map(v -> v * v))
.subscribe(...);

Create

public final <R> Observable<R> map(Func1<? super T, ? extends R> func) {
    return new ObservableMap<T, R>(this, func);
}

Conclusion

Introduction

1. many sequences are started from constant or quasi-constant sources such as just(), from(T[]), from(Iterable), fromCallable() which don't really need the thread-safety dance in a sequence of operators,
2. some pairs of operators can share internal components such as Queues and
3. some operators can tell if they consumed the value or dropped it, avoiding request(1) call overhead.

Generations

0th generation

1st generation

2nd generation

3rd generation

4th generation

5+ generation

The Rx lifecycle

1. Assembly-time. This is the time when you write up just().subscribeOn().map() and assign that to a field or variable of type Observable/Publisher. This is the main difference between Future-based APIs (Promise, CompletableFuture, etc.) which if support some fluent API where there isn't a separate assembly time but some form of interleaving among the 3 points.
2. Subscription-time. This is the time when a Subscriber subscribes to a sequence at its very end and triggers a "storm" of subscriptions inside the various operators. On one hand, it has an upstream-directed edge and on the other hand, a downstream-directed edge of calls to setProducer/onSubscribe. This is when subscription-sideeffects are triggered and generally no value is flowing through the pipeline.
3. Runtime. This is the time when items are generated followed by zero or one terminal event of error/completion.

Operator-fusion

Macro-fusion

Observable.range(1, 10)
   .filter(v -> v % 3 == 0)
   .filter(v -> v % 2 == 0)
   .map(v -> v + 1)
   .map(v -> v * v)
   .subscribe(System.out::println);

Predicate<Integer> p1 = v -> v % 3 == 0;
Predicate<Integer> p2 = v -> v % 2 == 0;

Predicate<Integer> p3 = v -> p1.test(v) && p2.test(v);

Function<Integer, Integer> f1 = v -> v + 1;
Function<Integer, Integer> f2 = v -> v * v;

Function<Integer, Integer> f3 = v -> f2.apply(f1.apply(v));

Micro-fusion

Invalid fusions

source.flatMap(u -> range(1, 2).map(v -> heavyComputation(v))
    .observeOn(AndroidSchedulers.mainThread()))
.subscribe(...)

Conclusion

Introduction

Wrapping

public final class MyObservable<T> {
    private Observable<T> actual;
    public MyObservable<T>(Observable<T> actual) {
        this.actual = actual;
    }
}

    // ...
    public static <T> MyObservable<T> create(Observable<T> o) {
        return new MyObservable<T>(o);
    }

    public static <T> MyObservable<T> just(T value) {
        return create(Observable.just(value));
    }

    public final MyObservable<T> goAsync() {
        return create(actual.subscribeOn(Schedulers.io())
            .observeOn(AndroidSchedulers.mainThread()));
    }

    public final <R> MyObservable<R> map(Func1<T, R> mapper) {
        return create(actual.map(mapper));
    }

    public final void subscribe(Subscriber<? super T> subscriber) {
        actual.subscribe(subscriber);
    }
    // ...

Interoperation

public class MyObservable<T> implements Publisher<T> {
    // ...
    @Override
    public void subscribe(Subscriber<? super T> subscriber) {
        actual.subscribe(subscriber);
    }
    // ...
}

Extension

    public class MyObservable<T, S extends MyObservable<T, S>> implements Publisher<T> {
       
        final Publisher<? extends T> actual;
       
        public MyObservable(Publisher<? extends T> actual) {
            this.actual = actual;
        }
       
        @SuppressWarnings("unchecked")
        public <R, U extends MyObservable<R, U>> U wrap(Publisher<? extends R> my) {
            return (U)new MyObservable<R, S>(my);
        }
       
        public final <R, U extends MyObservable<R, U>> U map(Function<? super T, ? extends R> mapper) {
            return wrap(Flowable.fromPublisher(actual).map(mapper));
        }
       
        @Override
        public void subscribe(Subscriber<? super T> s) {
            actual.subscribe(s);
        }
    }