2.x: add doFinally for handling post terminal or cancel cleanup (#4831)

src/main/java/io/reactivex/Flowable.java

@@ -7324,6 +7324,35 @@ public final Flowable<T> distinctUntilChanged(BiPredicate<? super T, ? super T>
         return RxJavaPlugins.onAssembly(new FlowableDistinctUntilChanged<T, T>(this, Functions.<T>identity(), comparer));
     }
 
+    /**
+     * Calls the specified action after this Flowable signals onError or onCompleted or gets cancelled by
+     * the downstream.
+     * <p>In case of a race between a terminal event and a cancellation, the provided {@code onFinally} action
+     * is executed at once per subscription.
+     * <p>Note that the {@code onFinally} action is shared between subscriptions and as such
+     * should be thread-safe.
+     * <dl>
+     *  <dt><b>Backpressure:</b></dt>
+     *  <dd>The operator doesn't interfere with backpressure which is determined by the source {@code Publisher}'s backpressure
+     *  behavior.</dd>
+     *  <dt><b>Scheduler:</b></dt>
+     *  <dd>{@code doFinally} does not operate by default on a particular {@link Scheduler}.</dd>
+     *  <td><b>Operator-fusion:</b></dt>
+     *  <dd>This operator supports normal and conditional Subscribers as well as boundary-limited
+     *  synchronous or asynchronous queue-fusion.</dd>
+     * </dl>
+     * @param onFinally the action called when this Flowable terminates or gets cancelled
+     * @return the new Flowable instance
+     * @since 2.0.1 - experimental
+     */
+    @BackpressureSupport(BackpressureKind.PASS_THROUGH)
+    @SchedulerSupport(SchedulerSupport.NONE)
+    @Experimental
+    public final Flowable<T> doFinally(Action onFinally) {
+        ObjectHelper.requireNonNull(onFinally, "onFinally is null");
+        return RxJavaPlugins.onAssembly(new FlowableDoFinally<T>(this, onFinally));
+    }
+
     /**
      * Registers an {@link Action} to be called when this Publisher invokes either
      * {@link Subscriber#onComplete onComplete} or {@link Subscriber#onError onError}.

src/main/java/io/reactivex/internal/operators/flowable/FlowableDoFinally.java

@@ -0,0 +1,262 @@
+/**
+ * Copyright 2016 Netflix, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
+ * compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is
+ * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
+ * the License for the specific language governing permissions and limitations under the License.
+ */
+
+package io.reactivex.internal.operators.flowable;
+
+import org.reactivestreams.*;
+
+import io.reactivex.annotations.Experimental;
+import io.reactivex.exceptions.Exceptions;
+import io.reactivex.functions.Action;
+import io.reactivex.internal.fuseable.*;
+import io.reactivex.internal.subscriptions.*;
+import io.reactivex.plugins.RxJavaPlugins;
+
+/**
+ * Execute an action after an onError, onComplete or a cancel event.
+ *
+ * @param <T> the value type
+ * @since 2.0.1 - experimental
+ */
+@Experimental
+public final class FlowableDoFinally<T> extends AbstractFlowableWithUpstream<T, T> {
+
+    final Action onFinally;
+
+    public FlowableDoFinally(Publisher<T> source, Action onFinally) {
+        super(source);
+        this.onFinally = onFinally;
+    }
+
+    @Override
+    protected void subscribeActual(Subscriber<? super T> s) {
+        if (s instanceof ConditionalSubscriber) {
+            source.subscribe(new DoFinallyConditionalSubscriber<T>((ConditionalSubscriber<? super T>)s, onFinally));
+        } else {
+            source.subscribe(new DoFinallySubscriber<T>(s, onFinally));
+        }
+    }
+
+    static final class DoFinallySubscriber<T> extends BasicIntQueueSubscription<T> implements Subscriber<T> {
+
+        private static final long serialVersionUID = 4109457741734051389L;
+
+        final Subscriber<? super T> actual;
+
+        final Action onFinally;
+
+        Subscription s;
+
+        QueueSubscription<T> qs;
+
+        boolean syncFused;
+
+        DoFinallySubscriber(Subscriber<? super T> actual, Action onFinally) {
+            this.actual = actual;
+            this.onFinally = onFinally;
+        }
+
+        @SuppressWarnings("unchecked")
+        @Override
+        public void onSubscribe(Subscription s) {
+            if (SubscriptionHelper.validate(this.s, s)) {
+                this.s = s;
+                if (s instanceof QueueSubscription) {
+                    this.qs = (QueueSubscription<T>)s;
+                }
+
+                actual.onSubscribe(this);
+            }
+        }
+
+        @Override
+        public void onNext(T t) {
+            actual.onNext(t);
+        }
+
+        @Override
+        public void onError(Throwable t) {
+            actual.onError(t);
+            runFinally();
+        }
+
+        @Override
+        public void onComplete() {
+            actual.onComplete();
+            runFinally();
+        }
+
+        @Override
+        public void cancel() {
+            s.cancel();
+            runFinally();
+        }
+
+        @Override
+        public void request(long n) {
+            s.request(n);
+        }
+
+        @Override
+        public int requestFusion(int mode) {
+            QueueSubscription<T> qs = this.qs;
+            if (qs != null && (mode & BOUNDARY) == 0) {
+                int m = qs.requestFusion(mode);
+                if (m != NONE) {
+                    syncFused = m == SYNC;
+                }
+                return m;
+            }
+            return NONE;
+        }
+
+        @Override
+        public void clear() {
+            qs.clear();
+        }
+
+        @Override
+        public boolean isEmpty() {
+            return qs.isEmpty();
+        }
+
+        @Override
+        public T poll() throws Exception {
+            T v = qs.poll();
+            if (v == null && syncFused) {
+                runFinally();
+            }
+            return v;
+        }
+
+        void runFinally() {
+            if (compareAndSet(0, 1)) {
+                try {
+                    onFinally.run();
+                } catch (Throwable ex) {
+                    Exceptions.throwIfFatal(ex);
+                    RxJavaPlugins.onError(ex);
+                }
+            }
+        }
+    }
+
+    static final class DoFinallyConditionalSubscriber<T> extends BasicIntQueueSubscription<T> implements ConditionalSubscriber<T> {
+
+        private static final long serialVersionUID = 4109457741734051389L;
+
+        final ConditionalSubscriber<? super T> actual;
+
+        final Action onFinally;
+
+        Subscription s;
+
+        QueueSubscription<T> qs;
+
+        boolean syncFused;
+
+        DoFinallyConditionalSubscriber(ConditionalSubscriber<? super T> actual, Action onFinally) {
+            this.actual = actual;
+            this.onFinally = onFinally;
+        }
+
+        @SuppressWarnings("unchecked")
+        @Override
+        public void onSubscribe(Subscription s) {
+            if (SubscriptionHelper.validate(this.s, s)) {
+                this.s = s;
+                if (s instanceof QueueSubscription) {
+                    this.qs = (QueueSubscription<T>)s;
+                }
+
+                actual.onSubscribe(this);
+            }
+        }
+
+        @Override
+        public void onNext(T t) {
+            actual.onNext(t);
+        }
+
+        @Override
+        public boolean tryOnNext(T t) {
+            return actual.tryOnNext(t);
+        }
+
+        @Override
+        public void onError(Throwable t) {
+            actual.onError(t);
+            runFinally();
+        }
+
+        @Override
+        public void onComplete() {
+            actual.onComplete();
+            runFinally();
+        }
+
+        @Override
+        public void cancel() {
+            s.cancel();
+            runFinally();
+        }
+
+        @Override
+        public void request(long n) {
+            s.request(n);
+        }
+
+        @Override
+        public int requestFusion(int mode) {
+            QueueSubscription<T> qs = this.qs;
+            if (qs != null && (mode & BOUNDARY) == 0) {
+                int m = qs.requestFusion(mode);
+                if (m != NONE) {
+                    syncFused = m == SYNC;
+                }
+                return m;
+            }
+            return NONE;
+        }
+
+        @Override
+        public void clear() {
+            qs.clear();
+        }
+
+        @Override
+        public boolean isEmpty() {
+            return qs.isEmpty();
+        }
+
+        @Override
+        public T poll() throws Exception {
+            T v = qs.poll();
+            if (v == null && syncFused) {
+                runFinally();
+            }
+            return v;
+        }
+
+        void runFinally() {
+            if (compareAndSet(0, 1)) {
+                try {
+                    onFinally.run();
+                } catch (Throwable ex) {
+                    Exceptions.throwIfFatal(ex);
+                    RxJavaPlugins.onError(ex);
+                }
+            }
+        }
+    }
+}