Adding ScheduledAction to public API

[akarnokd]

Resubmit of #2579.

I've copied the internal ScheduledAction into the public rx.schedulers package to allow custom Scheduler implementors in other projects to take advantage of its correct unsubscription management.

I've removed the internal ScheduledAction. Since relying on internal features are discouraged anyway, use places outside RxJava need to be updated. Deprecating it doesn't work because the class is final and the internals now return the new rx.schedulers.ScheduledAction and would result in ClassCastException anyway.

I've introduced a system-wide parameter io.reactivex.scheduler.interrupt-on-unsubscribe to enable interruption globally. In addition, each ScheduledAction has its own setInterruptOnUnsubscribe which allows enabling/disabling interrupts on an individual basis (overrides the default from the system-wide parameter above for the instance).

I've also added detailed documentation to it and (while I was in the mood) to the NewThreadWorker.

[benjchristensen]

Trying to think through the implications of this being part of the public API. Is it okay if I leave this out of 1.0.5 and we can follow up with 1.0.6 soon?

[akarnokd]

Sure.

[zsxwing]

It's better to add @experimental or @beta for the new public class.

[benjchristensen]

I was playing with this in Hystrix with @mattrjacobs and it seemed we could achieve the desired reuse by adding a static factor methods to Schedulers without needing to expose this implementation detail. The add, addParent stuff is very non-obvious and needs to be done "just right" or it doesn't work. All of that seems like it should be encapsulated behind a factory method.

Here is example code: https://github.com/Netflix/Hystrix/blob/19320db57cdb4b600021875133c7ec61b4c96b82/hystrix-core/src/main/java/com/netflix/hystrix/strategy/concurrency/HystrixContextScheduler.java#L160-171

Could we replace this with an API call such as Schedulers.submitTo(executor, action, subscription, shouldInterrupt);?

[akarnokd]

Sounds like a good alternative, although it would require the subscription to be a CompositeSubscription. I'd introduce a SubscriptionCollection interface with add, remove and removeSilently so more optimized collections may be used.

[mattrjacobs]

+1 on moving this complexity to RxJava and not leaving it to consumers to get right.

[akarnokd]

Okay. I'll add the utility method and keep the ScheduledAction changes private.

[akarnokd]

See #2761 for the new proposal.