2.x: add Completable.cache()

[akarnokd]

This PR adds the operator cache() to Completable to cache the terminal event of a Completable sequence.

I came across the need for this when answering a question where the intent of using Completable was to indicate an operation has completed but not actually trigger the operation whenever one subscribed.

A small drawback, just like with other cache() operators is that once connected, there is no way for cancel it from within the operator itself. Returning Completable & Disposable doesn't work because of the the type restriction of RxJavaPlugins.onAssembly. There could be a cache(Consumer<? super Disposable> onDispose) overload or an example showing source.ambWith(disposer).cache().

[codecov-io]

Current coverage is 95.62% (diff: 100%)

Merging #4930 into 2.x will decrease coverage by 0.05%

@@                2.x      #4930   diff @@
==========================================
  Files           586        587     +1   
  Lines         37452      37519    +67   
  Methods           0          0          
  Messages          0          0          
  Branches       5627       5644    +17   
==========================================
+ Hits          35833      35877    +44   
- Misses          682        696    +14   
- Partials        937        946     +9   

Powered by Codecov. Last update 9b91d4e...267994f

[PaulWoitaschek]

Great improvement, thanks!

In one of my projects I applied this transformer to a lot of sequences:

private static final CompletableTransformer cache = completable ->
    completable.toObservable()
      .cacheWithInitialCapacity(1)
      .ignoreElements();