Great stuff! I knocked up some backpressure support a couple of days ago for RxJavaString and was quite bothered by the DRY aspect. This will make implementing OnSubscribe way easier let alone getting backpressure support for free. Thanks!

Just so I remember, an unrelated test failure:

rx.schedulers.TrampolineSchedulerTest > testSequenceOfDelayedActions FAILED
org.mockito.exceptions.verification.VerificationInOrderFailure:
Verification in order failure
Wanted but not invoked:
action0.call();
-> at rx.schedulers.AbstractSchedulerTests.testSequenceOfDelayedActions(AbstractSchedulerTests.java:220)
Wanted anywhere AFTER following interaction:
action0.call();
-> at rx.schedulers.SleepingAction.call(SleepingAction.java:53)

I wonder if this is the queue capacity bug of the JCTools queues we adapted.

Few enhancement options:

• SubscriptionState could be a producer as well, no need for separate class.
• there is no point in refcounting a null custom state and thus overhead could be reduced.

In addition, there is a potential bug when a next call doesn't produce an event nor does it unsubscribe. With backpressure present, this may stop producing altogether; without backpressure, it may loop indefinitely. This comes up whne phasing is needed by the state machine the programmer implements. So either we detect phase change but no events, we just loop again; or we throw an exception stating the lack of event emissions or explicit unsubscription.

Can you give an example for the method

AbstractOnSubscribe.onSubscribe(Subscriber<? super T> subscriber)

where an overriding implementation uses the subscriber?

The subscriber is not accessible in next by default to make sure developers only interact with the abstraction, but there might be a case you somehow need the Subscriber, or you need to add some things to unsubscribe if downstream unsubscribes. That might be a Scheduler.Worker, another Subscriber to another Observable. Now with the lambda convenience cases, I just forgot about this by accident. I'll make the fixes in a day.

Re the potential bug, what about making next even simpler by not including a reference to the subscriber (or the abstraction) at all:

Optional<T> next(S state);

The Iterable<T> use case would look like:

@Override
public Optional<T> next(Iterator<T> state) {
    if (state.hasNext())
        return Optional.of(state.next());
    else 
       return Optional.absent();
}

Had another look at your use cases and I see that we would have less flexibility like with calling onComplete straight after the it.next call in your Iterator<T> example. Nevertheless it might be an attractive simplification in a class like AbstractOnSubscribeSimple.

AbstractIterable doesn't seem to give the possibility to have custom state per iterator() calls, so I wanted to work around that. Your iterator example has some limitations, namely you can only produce one response per call and you need to wrap/unwrap things which leads to really unnecessary GC.

What I've said about free backpressure with AbstractIterable is still true. If you can express your iterative computation with it, then there is no need to use AOS.

This looks really useful, and the docs in the code are great.

Would you mind rebasing the commits since this is brand new stuff and could be cleanly committed as a single commit?

Thank you for marking it as Experimental as it would be good to get feedback and allow changes before we commit to it.

Is there anything we can learn from generators? (see https://github.com/Reactive-Extensions/RxJS/blob/master/doc/gettingstarted/generators.md)

/cc @headinthebox as I think it would be good to have your input on this.

On my TODO!

Please ignore my previous comments. I just misunderstood the meaning of phase.

Is there anything we can learn from generators?

Without language support, you are at a loss.

Seems like a useful addition; I agree about making it available as experimental so we can evolve it.

Without language support, you are at a loss.

I know we can't do what real generator implementations do with yield. Are the signatures of generators completely affected by the use of yield and thus not at all useful to this exploration?

Seems like a useful addition; I agree about making it available as experimental so we can evolve it.

Good, glad there is alignment. I'm going to merge #1946 so we can start using and iterating.