Debian Codegraph @

src/main/java/io/reactivex/rxjava3/processors/MulticastProcessor.java

raw
1 /*
2 * Copyright (c) 2016-present, RxJava Contributors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
5 * compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License is
10 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
11 * the License for the specific language governing permissions and limitations under the License.
12 */
13
14 package io.reactivex.rxjava3.processors;
15
16 import java.util.concurrent.atomic.*;
17
18 import org.reactivestreams.*;
19
20 import io.reactivex.rxjava3.annotations.*;
21 import io.reactivex.rxjava3.exceptions.*;
22 import io.reactivex.rxjava3.internal.functions.ObjectHelper;
23 import io.reactivex.rxjava3.internal.subscriptions.*;
24 import io.reactivex.rxjava3.internal.util.*;
25 import io.reactivex.rxjava3.operators.*;
26 import io.reactivex.rxjava3.plugins.RxJavaPlugins;
27
28 /**
29 * A {@link FlowableProcessor} implementation that coordinates downstream requests through
30 * a front-buffer and stable-prefetching, optionally canceling the upstream if all
31 * subscribers have cancelled.
32 * <p>
33 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/MulticastProcessor.png" alt="">
34 * <p>
35 * This processor does not have a public constructor by design; a new empty instance of this
36 * {@code MulticastProcessor} can be created via the following {@code create} methods that
37 * allow configuring it:
38 * <ul>
39 * <li>{@link #create()}: create an empty {@code MulticastProcessor} with
40 * {@link io.reactivex.rxjava3.core.Flowable#bufferSize() Flowable.bufferSize()} prefetch amount
41 * and no reference counting behavior.</li>
42 * <li>{@link #create(int)}: create an empty {@code MulticastProcessor} with
43 * the given prefetch amount and no reference counting behavior.</li>
44 * <li>{@link #create(boolean)}: create an empty {@code MulticastProcessor} with
45 * {@link io.reactivex.rxjava3.core.Flowable#bufferSize() Flowable.bufferSize()} prefetch amount
46 * and an optional reference counting behavior.</li>
47 * <li>{@link #create(int, boolean)}: create an empty {@code MulticastProcessor} with
48 * the given prefetch amount and an optional reference counting behavior.</li>
49 * </ul>
50 * <p>
51 * When the reference counting behavior is enabled, the {@code MulticastProcessor} cancels its
52 * upstream when all {@link Subscriber}s have cancelled. Late {@code Subscriber}s will then be
53 * immediately completed.
54 * <p>
55 * Because {@code MulticastProcessor} implements the {@link Subscriber} interface, calling
56 * {@code onSubscribe} is mandatory (<a href="https://github.com/reactive-streams/reactive-streams-jvm#2.12">Rule 2.12</a>).
57 * If {@code MulticastProcessor} should run standalone, i.e., without subscribing the {@code MulticastProcessor} to another {@link Publisher},
58 * use {@link #start()} or {@link #startUnbounded()} methods to initialize the internal buffer.
59 * Failing to do so will lead to a {@link NullPointerException} at runtime.
60 * <p>
61 * Use {@link #offer(Object)} to try and offer/emit items but don't fail if the
62 * internal buffer is full.
63 * <p>
64 * A {@code MulticastProcessor} is a {@link Processor} type in the Reactive Streams specification,
65 * {@code null}s are not allowed (<a href="https://github.com/reactive-streams/reactive-streams-jvm#2.13">Rule 2.13</a>) as
66 * parameters to {@link #onSubscribe(Subscription)}, {@link #offer(Object)}, {@link #onNext(Object)} and {@link #onError(Throwable)}.
67 * Such calls will result in a {@link NullPointerException} being thrown and the processor's state is not changed.
68 * <p>
69 * Since a {@code MulticastProcessor} is a {@link io.reactivex.rxjava3.core.Flowable}, it supports backpressure.
70 * The backpressure from the currently subscribed {@link Subscriber}s are coordinated by emitting upstream
71 * items only if all of those {@code Subscriber}s have requested at least one item. This behavior
72 * is also called <em>lockstep-mode</em> because even if some {@code Subscriber}s can take any number
73 * of items, other {@code Subscriber}s requesting less or infrequently will slow down the overall
74 * throughput of the flow.
75 * <p>
76 * Calling {@link #onNext(Object)}, {@link #offer(Object)}, {@link #onError(Throwable)} and {@link #onComplete()}
77 * is required to be serialized (called from the same thread or called non-overlappingly from different threads
78 * through external means of serialization). The {@link #toSerialized()} method available to all {@link FlowableProcessor}s
79 * provides such serialization and also protects against reentrance (i.e., when a downstream {@code Subscriber}
80 * consuming this processor also wants to call {@link #onNext(Object)} on this processor recursively).
81 * <p>
82 * This {@code MulticastProcessor} supports the standard state-peeking methods {@link #hasComplete()}, {@link #hasThrowable()},
83 * {@link #getThrowable()} and {@link #hasSubscribers()}. This processor doesn't allow peeking into its buffer.
84 * <p>
85 * When this {@code MulticastProcessor} is terminated via {@link #onError(Throwable)} or {@link #onComplete()},
86 * all previously signaled but not yet consumed items will be still available to {@code Subscriber}s and the respective
87 * terminal even is only emitted when all previous items have been successfully delivered to {@code Subscriber}s.
88 * If there are no {@code Subscriber}s, the remaining items will be buffered indefinitely.
89 * <p>
90 * The {@code MulticastProcessor} does not support clearing its cached events (to appear empty again).
91 * <dl>
92 * <dt><b>Backpressure:</b></dt>
93 * <dd>The backpressure from the currently subscribed {@code Subscriber}s are coordinated by emitting upstream
94 * items only if all of those {@code Subscriber}s have requested at least one item. This behavior
95 * is also called <em>lockstep-mode</em> because even if some {@code Subscriber}s can take any number
96 * of items, other {@code Subscriber}s requesting less or infrequently will slow down the overall
97 * throughput of the flow.</dd>
98 * <dt><b>Scheduler:</b></dt>
99 * <dd>{@code MulticastProcessor} does not operate by default on a particular {@link io.reactivex.rxjava3.core.Scheduler} and
100 * the {@code Subscriber}s get notified on an arbitrary thread in a serialized fashion.</dd>
101 * </dl>
102 * <p>
103 * Example:
104 * <pre><code>
105 MulticastProcessor&lt;Integer&gt; mp = Flowable.range(1, 10)
106 .subscribeWith(MulticastProcessor.create());
107
108 mp.test().assertResult(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
109
110 // --------------------
111
112 MulticastProcessor&lt;Integer&gt; mp2 = MulticastProcessor.create(4);
113 mp2.start();
114
115 assertTrue(mp2.offer(1));
116 assertTrue(mp2.offer(2));
117 assertTrue(mp2.offer(3));
118 assertTrue(mp2.offer(4));
119
120 assertFalse(mp2.offer(5));
121
122 mp2.onComplete();
123
124 mp2.test().assertResult(1, 2, 3, 4);
125 * </code></pre>
126 * <p>History: 2.1.14 - experimental
127 * @param <T> the input and output value type
128 * @since 2.2
129 */
130 @BackpressureSupport(BackpressureKind.FULL)
131 @SchedulerSupport(SchedulerSupport.NONE)
132 public final class MulticastProcessor<@NonNull T> extends FlowableProcessor<T> {
133
134 final AtomicInteger wip;
135
136 final AtomicReference<Subscription> upstream;
137
138 final AtomicReference<MulticastSubscription<T>[]> subscribers;
139
140 final int bufferSize;
141
142 final int limit;
143
144 final boolean refcount;
145
146 volatile SimpleQueue<T> queue;
147
148 volatile boolean done;
149 volatile Throwable error;
150
151 int consumed;
152
153 int fusionMode;
154
155 @SuppressWarnings("rawtypes")
156 static final MulticastSubscription[] EMPTY = new MulticastSubscription[0];
157
158 @SuppressWarnings("rawtypes")
159 static final MulticastSubscription[] TERMINATED = new MulticastSubscription[0];
160
161 /**
162 * Constructs a fresh instance with the default Flowable.bufferSize() prefetch
163 * amount and no refCount-behavior.
164 * @param <T> the input and output value type
165 * @return the new MulticastProcessor instance
166 */
167 @CheckReturnValue
168 @NonNull
169 public static <T> MulticastProcessor<T> create() {
170 return new MulticastProcessor<>(bufferSize(), false);
171 }
172
173 /**
174 * Constructs a fresh instance with the default Flowable.bufferSize() prefetch
175 * amount and the optional refCount-behavior.
176 * @param <T> the input and output value type
177 * @param refCount if true and if all Subscribers have canceled, the upstream
178 * is cancelled
179 * @return the new MulticastProcessor instance
180 */
181 @CheckReturnValue
182 @NonNull
183 public static <T> MulticastProcessor<T> create(boolean refCount) {
184 return new MulticastProcessor<>(bufferSize(), refCount);
185 }
186
187 /**
188 * Constructs a fresh instance with the given prefetch amount and no refCount behavior.
189 * @param bufferSize the prefetch amount
190 * @param <T> the input and output value type
191 * @return the new MulticastProcessor instance
192 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
193 */
194 @CheckReturnValue
195 @NonNull
196 public static <T> MulticastProcessor<T> create(int bufferSize) {
197 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
198 return new MulticastProcessor<>(bufferSize, false);
199 }
200
201 /**
202 * Constructs a fresh instance with the given prefetch amount and the optional
203 * refCount-behavior.
204 * @param bufferSize the prefetch amount
205 * @param refCount if true and if all Subscribers have canceled, the upstream
206 * is cancelled
207 * @param <T> the input and output value type
208 * @return the new MulticastProcessor instance
209 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
210 */
211 @CheckReturnValue
212 @NonNull
213 public static <T> MulticastProcessor<T> create(int bufferSize, boolean refCount) {
214 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
215 return new MulticastProcessor<>(bufferSize, refCount);
216 }
217
218 /**
219 * Constructs a fresh instance with the given prefetch amount and the optional
220 * refCount-behavior.
221 * @param bufferSize the prefetch amount
222 * @param refCount if true and if all Subscribers have canceled, the upstream
223 * is cancelled
224 */
225 @SuppressWarnings("unchecked")
226 MulticastProcessor(int bufferSize, boolean refCount) {
227 this.bufferSize = bufferSize;
228 this.limit = bufferSize - (bufferSize >> 2);
229 this.wip = new AtomicInteger();
230 this.subscribers = new AtomicReference<>(EMPTY);
231 this.upstream = new AtomicReference<>();
232 this.refcount = refCount;
233 }
234
235 /**
236 * Initializes this Processor by setting an upstream Subscription that
237 * ignores request amounts, uses a fixed buffer
238 * and allows using the onXXX and offer methods
239 * afterwards.
240 */
241 public void start() {
242 if (SubscriptionHelper.setOnce(upstream, EmptySubscription.INSTANCE)) {
243 queue = new SpscArrayQueue<>(bufferSize);
244 }
245 }
246
247 /**
248 * Initializes this Processor by setting an upstream Subscription that
249 * ignores request amounts, uses an unbounded buffer
250 * and allows using the onXXX and offer methods
251 * afterwards.
252 */
253 public void startUnbounded() {
254 if (SubscriptionHelper.setOnce(upstream, EmptySubscription.INSTANCE)) {
255 queue = new SpscLinkedArrayQueue<>(bufferSize);
256 }
257 }
258
259 @Override
260 public void onSubscribe(@NonNull Subscription s) {
261 if (SubscriptionHelper.setOnce(upstream, s)) {
262 if (s instanceof QueueSubscription) {
263 @SuppressWarnings("unchecked")
264 QueueSubscription<T> qs = (QueueSubscription<T>)s;
265
266 int m = qs.requestFusion(QueueSubscription.ANY);
267 if (m == QueueSubscription.SYNC) {
268 fusionMode = m;
269 queue = qs;
270 done = true;
271 drain();
272 return;
273 }
274 if (m == QueueSubscription.ASYNC) {
275 fusionMode = m;
276 queue = qs;
277
278 s.request(bufferSize);
279 return;
280 }
281 }
282
283 queue = new SpscArrayQueue<>(bufferSize);
284
285 s.request(bufferSize);
286 }
287 }
288
289 @Override
290 public void onNext(@NonNull T t) {
291 if (done) {
292 return;
293 }
294 if (fusionMode == QueueSubscription.NONE) {
295 ExceptionHelper.nullCheck(t, "onNext called with a null value.");
296 if (!queue.offer(t)) {
297 SubscriptionHelper.cancel(upstream);
298 onError(new MissingBackpressureException());
299 return;
300 }
301 }
302 drain();
303 }
304
305 /**
306 * Tries to offer an item into the internal queue and returns false
307 * if the queue is full.
308 * @param t the item to offer, not {@code null}
309 * @return true if successful, false if the queue is full
310 * @throws NullPointerException if {@code t} is {@code null}
311 * @throws IllegalStateException if the processor is in fusion mode
312 */
313 @CheckReturnValue
314 public boolean offer(@NonNull T t) {
315 ExceptionHelper.nullCheck(t, "offer called with a null value.");
316 if (done) {
317 return false;
318 }
319 if (fusionMode == QueueSubscription.NONE) {
320 if (queue.offer(t)) {
321 drain();
322 return true;
323 }
324 return false;
325 }
326 throw new IllegalStateException("offer() should not be called in fusion mode!");
327 }
328
329 @Override
330 public void onError(@NonNull Throwable t) {
331 ExceptionHelper.nullCheck(t, "onError called with a null Throwable.");
332 if (!done) {
333 error = t;
334 done = true;
335 drain();
336 return;
337 }
338 RxJavaPlugins.onError(t);
339 }
340
341 @Override
342 public void onComplete() {
343 done = true;
344 drain();
345 }
346
347 @Override
348 @CheckReturnValue
349 public boolean hasSubscribers() {
350 return subscribers.get().length != 0;
351 }
352
353 @Override
354 @CheckReturnValue
355 public boolean hasThrowable() {
356 return done && error != null;
357 }
358
359 @Override
360 @CheckReturnValue
361 public boolean hasComplete() {
362 return done && error == null;
363 }
364
365 @Override
366 @CheckReturnValue
367 public Throwable getThrowable() {
368 return done ? error : null;
369 }
370
371 @Override
372 protected void subscribeActual(@NonNull Subscriber<? super T> s) {
373 MulticastSubscription<T> ms = new MulticastSubscription<>(s, this);
374 s.onSubscribe(ms);
375 if (add(ms)) {
376 if (ms.get() == Long.MIN_VALUE) {
377 remove(ms);
378 } else {
379 drain();
380 }
381 } else {
382 if (done) {
383 Throwable ex = error;
384 if (ex != null) {
385 s.onError(ex);
386 return;
387 }
388 }
389 s.onComplete();
390 }
391 }
392
393 boolean add(MulticastSubscription<T> inner) {
394 for (;;) {
395 MulticastSubscription<T>[] a = subscribers.get();
396 if (a == TERMINATED) {
397 return false;
398 }
399 int n = a.length;
400 @SuppressWarnings("unchecked")
401 MulticastSubscription<T>[] b = new MulticastSubscription[n + 1];
402 System.arraycopy(a, 0, b, 0, n);
403 b[n] = inner;
404 if (subscribers.compareAndSet(a, b)) {
405 return true;
406 }
407 }
408 }
409
410 @SuppressWarnings("unchecked")
411 void remove(MulticastSubscription<T> inner) {
412 for (;;) {
413 MulticastSubscription<T>[] a = subscribers.get();
414 int n = a.length;
415 if (n == 0) {
416 return;
417 }
418
419 int j = -1;
420 for (int i = 0; i < n; i++) {
421 if (a[i] == inner) {
422 j = i;
423 break;
424 }
425 }
426
427 if (j < 0) {
428 break;
429 }
430
431 if (n == 1) {
432 if (refcount) {
433 if (subscribers.compareAndSet(a, TERMINATED)) {
434 SubscriptionHelper.cancel(upstream);
435 done = true;
436 break;
437 }
438 } else {
439 if (subscribers.compareAndSet(a, EMPTY)) {
440 break;
441 }
442 }
443 } else {
444 MulticastSubscription<T>[] b = new MulticastSubscription[n - 1];
445 System.arraycopy(a, 0, b, 0, j);
446 System.arraycopy(a, j + 1, b, j, n - j - 1);
447 if (subscribers.compareAndSet(a, b)) {
448 break;
449 }
450 }
451 }
452 }
453
454 @SuppressWarnings("unchecked")
455 void drain() {
456 if (wip.getAndIncrement() != 0) {
457 return;
458 }
459
460 int missed = 1;
461 AtomicReference<MulticastSubscription<T>[]> subs = subscribers;
462 int c = consumed;
463 int lim = limit;
464 int fm = fusionMode;
465
466 outer:
467 for (;;) {
468
469 SimpleQueue<T> q = queue;
470
471 if (q != null) {
472 MulticastSubscription<T>[] as = subs.get();
473 int n = as.length;
474
475 if (n != 0) {
476 long r = -1L;
477
478 for (MulticastSubscription<T> a : as) {
479 long ra = a.get();
480 if (ra >= 0L) {
481 if (r == -1L) {
482 r = ra - a.emitted;
483 } else {
484 r = Math.min(r, ra - a.emitted);
485 }
486 }
487 }
488
489 while (r > 0L) {
490 MulticastSubscription<T>[] bs = subs.get();
491
492 if (bs == TERMINATED) {
493 q.clear();
494 return;
495 }
496
497 if (as != bs) {
498 continue outer;
499 }
500
501 boolean d = done;
502
503 T v;
504
505 try {
506 v = q.poll();
507 } catch (Throwable ex) {
508 Exceptions.throwIfFatal(ex);
509 SubscriptionHelper.cancel(upstream);
510 d = true;
511 v = null;
512 error = ex;
513 done = true;
514 }
515 boolean empty = v == null;
516
517 if (d && empty) {
518 Throwable ex = error;
519 if (ex != null) {
520 for (MulticastSubscription<T> inner : subs.getAndSet(TERMINATED)) {
521 inner.onError(ex);
522 }
523 } else {
524 for (MulticastSubscription<T> inner : subs.getAndSet(TERMINATED)) {
525 inner.onComplete();
526 }
527 }
528 return;
529 }
530
531 if (empty) {
532 break;
533 }
534
535 for (MulticastSubscription<T> inner : as) {
536 inner.onNext(v);
537 }
538
539 r--;
540
541 if (fm != QueueSubscription.SYNC) {
542 if (++c == lim) {
543 c = 0;
544 upstream.get().request(lim);
545 }
546 }
547 }
548
549 if (r == 0) {
550 MulticastSubscription<T>[] bs = subs.get();
551
552 if (bs == TERMINATED) {
553 q.clear();
554 return;
555 }
556
557 if (as != bs) {
558 continue;
559 }
560
561 if (done && q.isEmpty()) {
562 Throwable ex = error;
563 if (ex != null) {
564 for (MulticastSubscription<T> inner : subs.getAndSet(TERMINATED)) {
565 inner.onError(ex);
566 }
567 } else {
568 for (MulticastSubscription<T> inner : subs.getAndSet(TERMINATED)) {
569 inner.onComplete();
570 }
571 }
572 return;
573 }
574 }
575 }
576 }
577
578 consumed = c;
579 missed = wip.addAndGet(-missed);
580 if (missed == 0) {
581 break;
582 }
583 }
584 }
585
586 static final class MulticastSubscription<@NonNull T> extends AtomicLong implements Subscription {
587
588 private static final long serialVersionUID = -363282618957264509L;
589
590 final Subscriber<? super T> downstream;
591
592 final MulticastProcessor<T> parent;
593
594 long emitted;
595
596 MulticastSubscription(Subscriber<? super T> actual, MulticastProcessor<T> parent) {
597 this.downstream = actual;
598 this.parent = parent;
599 }
600
601 @Override
602 public void request(long n) {
603 if (SubscriptionHelper.validate(n)) {
604 long r = BackpressureHelper.addCancel(this, n);
605 if (r != Long.MIN_VALUE && r != Long.MAX_VALUE) {
606 parent.drain();
607 }
608 }
609 }
610
611 @Override
612 public void cancel() {
613 if (getAndSet(Long.MIN_VALUE) != Long.MIN_VALUE) {
614 parent.remove(this);
615 }
616 }
617
618 void onNext(T t) {
619 if (get() != Long.MIN_VALUE) {
620 emitted++;
621 downstream.onNext(t);
622 }
623 }
624
625 void onError(Throwable t) {
626 if (get() != Long.MIN_VALUE) {
627 downstream.onError(t);
628 }
629 }
630
631 void onComplete() {
632 if (get() != Long.MIN_VALUE) {
633 downstream.onComplete();
634 }
635 }
636 }
637 }