Debian Codegraph @

src/main/java/io/reactivex/rxjava3/parallel/ParallelFlowable.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.parallel;
15
16 import java.util.*;
17 import java.util.stream.*;
18
19 import org.reactivestreams.*;
20
21 import io.reactivex.rxjava3.annotations.*;
22 import io.reactivex.rxjava3.core.*;
23 import io.reactivex.rxjava3.exceptions.MissingBackpressureException;
24 import io.reactivex.rxjava3.functions.*;
25 import io.reactivex.rxjava3.internal.functions.*;
26 import io.reactivex.rxjava3.internal.jdk8.*;
27 import io.reactivex.rxjava3.internal.operators.parallel.*;
28 import io.reactivex.rxjava3.internal.subscriptions.EmptySubscription;
29 import io.reactivex.rxjava3.internal.util.*;
30 import io.reactivex.rxjava3.plugins.RxJavaPlugins;
31
32 /**
33 * Abstract base class for parallel publishing of events signaled to an array of {@link Subscriber}s.
34 * <p>
35 * Use {@link #from(Publisher)} to start processing a regular {@link Publisher} in 'rails'.
36 * Use {@link #runOn(Scheduler)} to introduce where each 'rail' should run on thread-vise.
37 * Use {@link #sequential()} to merge the sources back into a single {@link Flowable}.
38 *
39 * <p>History: 2.0.5 - experimental; 2.1 - beta
40 * @param <T> the value type
41 * @since 2.2
42 */
43 public abstract class ParallelFlowable<@NonNull T> {
44
45 /**
46 * Subscribes an array of {@link Subscriber}s to this {@code ParallelFlowable} and triggers
47 * the execution chain for all 'rails'.
48 * <dl>
49 * <dt><b>Backpressure:</b></dt>
50 * <dd>The backpressure behavior/expectation is determined by the supplied {@code Subscriber}.</dd>
51 * <dt><b>Scheduler:</b></dt>
52 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
53 * </dl>
54 *
55 * @param subscribers the subscribers array to run in parallel, the number
56 * of items must be equal to the parallelism level of this {@code ParallelFlowable}
57 * @throws NullPointerException if {@code subscribers} is {@code null}
58 * @see #parallelism()
59 */
60 @BackpressureSupport(BackpressureKind.SPECIAL)
61 @SchedulerSupport(SchedulerSupport.NONE)
62 public abstract void subscribe(@NonNull Subscriber<? super T>[] subscribers);
63
64 /**
65 * Returns the number of expected parallel {@link Subscriber}s.
66 * @return the number of expected parallel {@code Subscriber}s
67 */
68 @CheckReturnValue
69 public abstract int parallelism();
70
71 /**
72 * Validates the number of subscribers and returns {@code true} if their number
73 * matches the parallelism level of this {@code ParallelFlowable}.
74 *
75 * @param subscribers the array of {@link Subscriber}s
76 * @return {@code true} if the number of subscribers equals to the parallelism level
77 * @throws NullPointerException if {@code subscribers} is {@code null}
78 * @throws IllegalArgumentException if {@code subscribers.length} is different from {@link #parallelism()}
79 */
80 protected final boolean validate(@NonNull Subscriber<@NonNull ?>[] subscribers) {
81 Objects.requireNonNull(subscribers, "subscribers is null");
82 int p = parallelism();
83 if (subscribers.length != p) {
84 Throwable iae = new IllegalArgumentException("parallelism = " + p + ", subscribers = " + subscribers.length);
85 for (Subscriber<@NonNull ?> s : subscribers) {
86 EmptySubscription.error(iae, s);
87 }
88 return false;
89 }
90 return true;
91 }
92
93 /**
94 * Take a {@link Publisher} and prepare to consume it on multiple 'rails' (number of CPUs)
95 * in a round-robin fashion.
96 * <dl>
97 * <dt><b>Backpressure:</b></dt>
98 * <dd>The operator honors the backpressure of the parallel rails and
99 * requests {@link Flowable#bufferSize} amount from the upstream, followed
100 * by 75% of that amount requested after every 75% received.</dd>
101 * <dt><b>Scheduler:</b></dt>
102 * <dd>{@code from} does not operate by default on a particular {@link Scheduler}.</dd>
103 * </dl>
104 * @param <T> the value type
105 * @param source the source {@code Publisher}
106 * @return the new {@code ParallelFlowable} instance
107 * @throws NullPointerException if {@code source} is {@code null}
108 */
109 @CheckReturnValue
110 @NonNull
111 @SchedulerSupport(SchedulerSupport.NONE)
112 @BackpressureSupport(BackpressureKind.FULL)
113 public static <@NonNull T> ParallelFlowable<T> from(@NonNull Publisher<? extends T> source) {
114 return from(source, Runtime.getRuntime().availableProcessors(), Flowable.bufferSize());
115 }
116
117 /**
118 * Take a {@link Publisher} and prepare to consume it on parallelism number of 'rails' in a round-robin fashion.
119 * <dl>
120 * <dt><b>Backpressure:</b></dt>
121 * <dd>The operator honors the backpressure of the parallel rails and
122 * requests {@link Flowable#bufferSize} amount from the upstream, followed
123 * by 75% of that amount requested after every 75% received.</dd>
124 * <dt><b>Scheduler:</b></dt>
125 * <dd>{@code from} does not operate by default on a particular {@link Scheduler}.</dd>
126 * </dl>
127 * @param <T> the value type
128 * @param source the source {@code Publisher}
129 * @param parallelism the number of parallel rails
130 * @return the new {@code ParallelFlowable} instance
131 * @throws NullPointerException if {@code source} is {@code null}
132 * @throws IllegalArgumentException if {@code parallelism} is non-positive
133 */
134 @CheckReturnValue
135 @NonNull
136 @SchedulerSupport(SchedulerSupport.NONE)
137 @BackpressureSupport(BackpressureKind.FULL)
138 public static <@NonNull T> ParallelFlowable<T> from(@NonNull Publisher<? extends T> source, int parallelism) {
139 return from(source, parallelism, Flowable.bufferSize());
140 }
141
142 /**
143 * Take a {@link Publisher} and prepare to consume it on parallelism number of 'rails' ,
144 * possibly ordered and round-robin fashion and use custom prefetch amount and queue
145 * for dealing with the source {@code Publisher}'s values.
146 * <dl>
147 * <dt><b>Backpressure:</b></dt>
148 * <dd>The operator honors the backpressure of the parallel rails and
149 * requests the {@code prefetch} amount from the upstream, followed
150 * by 75% of that amount requested after every 75% received.</dd>
151 * <dt><b>Scheduler:</b></dt>
152 * <dd>{@code from} does not operate by default on a particular {@link Scheduler}.</dd>
153 * </dl>
154 * @param <T> the value type
155 * @param source the source {@code Publisher}
156 * @param parallelism the number of parallel rails
157 * @param prefetch the number of values to prefetch from the source
158 * the source until there is a rail ready to process it.
159 * @return the new {@code ParallelFlowable} instance
160 * @throws NullPointerException if {@code source} is {@code null}
161 * @throws IllegalArgumentException if {@code parallelism} or {@code prefetch} is non-positive
162 */
163 @CheckReturnValue
164 @NonNull
165 @SchedulerSupport(SchedulerSupport.NONE)
166 @BackpressureSupport(BackpressureKind.FULL)
167 public static <@NonNull T> ParallelFlowable<T> from(@NonNull Publisher<? extends T> source,
168 int parallelism, int prefetch) {
169 Objects.requireNonNull(source, "source is null");
170 ObjectHelper.verifyPositive(parallelism, "parallelism");
171 ObjectHelper.verifyPositive(prefetch, "prefetch");
172
173 return RxJavaPlugins.onAssembly(new ParallelFromPublisher<>(source, parallelism, prefetch));
174 }
175
176 /**
177 * Maps the source values on each 'rail' to another value.
178 * <p>
179 * Note that the same {@code mapper} function may be called from multiple threads concurrently.
180 * <dl>
181 * <dt><b>Backpressure:</b></dt>
182 * <dd>The operator is a pass-through for backpressure and the behavior
183 * is determined by the upstream and downstream rail behaviors.</dd>
184 * <dt><b>Scheduler:</b></dt>
185 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
186 * </dl>
187 * @param <R> the output value type
188 * @param mapper the mapper function turning Ts into Rs.
189 * @return the new {@code ParallelFlowable} instance
190 * @throws NullPointerException if {@code mapper} is {@code null}
191 */
192 @CheckReturnValue
193 @NonNull
194 @SchedulerSupport(SchedulerSupport.NONE)
195 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
196 public final <@NonNull R> ParallelFlowable<R> map(@NonNull Function<? super T, ? extends R> mapper) {
197 Objects.requireNonNull(mapper, "mapper is null");
198 return RxJavaPlugins.onAssembly(new ParallelMap<>(this, mapper));
199 }
200
201 /**
202 * Maps the source values on each 'rail' to another value and
203 * handles errors based on the given {@link ParallelFailureHandling} enumeration value.
204 * <p>
205 * Note that the same {@code mapper} function may be called from multiple threads concurrently.
206 * <dl>
207 * <dt><b>Backpressure:</b></dt>
208 * <dd>The operator is a pass-through for backpressure and the behavior
209 * is determined by the upstream and downstream rail behaviors.</dd>
210 * <dt><b>Scheduler:</b></dt>
211 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
212 * </dl>
213 * <p>History: 2.0.8 - experimental
214 * @param <R> the output value type
215 * @param mapper the mapper function turning Ts into Rs.
216 * @param errorHandler the enumeration that defines how to handle errors thrown
217 * from the {@code mapper} function
218 * @return the new {@code ParallelFlowable} instance
219 * @throws NullPointerException if {@code mapper} or {@code errorHandler} is {@code null}
220 * @since 2.2
221 */
222 @CheckReturnValue
223 @NonNull
224 @SchedulerSupport(SchedulerSupport.NONE)
225 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
226 public final <@NonNull R> ParallelFlowable<R> map(@NonNull Function<? super T, ? extends R> mapper, @NonNull ParallelFailureHandling errorHandler) {
227 Objects.requireNonNull(mapper, "mapper is null");
228 Objects.requireNonNull(errorHandler, "errorHandler is null");
229 return RxJavaPlugins.onAssembly(new ParallelMapTry<>(this, mapper, errorHandler));
230 }
231
232 /**
233 * Maps the source values on each 'rail' to another value and
234 * handles errors based on the returned value by the handler function.
235 * <p>
236 * Note that the same {@code mapper} function may be called from multiple threads concurrently.
237 * <dl>
238 * <dt><b>Backpressure:</b></dt>
239 * <dd>The operator is a pass-through for backpressure and the behavior
240 * is determined by the upstream and downstream rail behaviors.</dd>
241 * <dt><b>Scheduler:</b></dt>
242 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
243 * </dl>
244 * <p>History: 2.0.8 - experimental
245 * @param <R> the output value type
246 * @param mapper the mapper function turning Ts into Rs.
247 * @param errorHandler the function called with the current repeat count and
248 * failure {@link Throwable} and should return one of the {@link ParallelFailureHandling}
249 * enumeration values to indicate how to proceed.
250 * @return the new {@code ParallelFlowable} instance
251 * @throws NullPointerException if {@code mapper} or {@code errorHandler} is {@code null}
252 * @since 2.2
253 */
254 @CheckReturnValue
255 @NonNull
256 @SchedulerSupport(SchedulerSupport.NONE)
257 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
258 public final <@NonNull R> ParallelFlowable<R> map(@NonNull Function<? super T, ? extends R> mapper, @NonNull BiFunction<? super Long, ? super Throwable, ParallelFailureHandling> errorHandler) {
259 Objects.requireNonNull(mapper, "mapper is null");
260 Objects.requireNonNull(errorHandler, "errorHandler is null");
261 return RxJavaPlugins.onAssembly(new ParallelMapTry<>(this, mapper, errorHandler));
262 }
263
264 /**
265 * Filters the source values on each 'rail'.
266 * <p>
267 * Note that the same predicate may be called from multiple threads concurrently.
268 * <dl>
269 * <dt><b>Backpressure:</b></dt>
270 * <dd>The operator is a pass-through for backpressure and the behavior
271 * is determined by the upstream and downstream rail behaviors.</dd>
272 * <dt><b>Scheduler:</b></dt>
273 * <dd>{@code filter} does not operate by default on a particular {@link Scheduler}.</dd>
274 * </dl>
275 * @param predicate the function returning {@code true} to keep a value or {@code false} to drop a value
276 * @return the new {@code ParallelFlowable} instance
277 * @throws NullPointerException if {@code predicate} is {@code null}
278 */
279 @CheckReturnValue
280 @NonNull
281 @SchedulerSupport(SchedulerSupport.NONE)
282 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
283 public final ParallelFlowable<T> filter(@NonNull Predicate<? super T> predicate) {
284 Objects.requireNonNull(predicate, "predicate is null");
285 return RxJavaPlugins.onAssembly(new ParallelFilter<>(this, predicate));
286 }
287
288 /**
289 * Filters the source values on each 'rail' and
290 * handles errors based on the given {@link ParallelFailureHandling} enumeration value.
291 * <p>
292 * Note that the same predicate may be called from multiple threads concurrently.
293 * <dl>
294 * <dt><b>Backpressure:</b></dt>
295 * <dd>The operator is a pass-through for backpressure and the behavior
296 * is determined by the upstream and downstream rail behaviors.</dd>
297 * <dt><b>Scheduler:</b></dt>
298 * <dd>{@code filter} does not operate by default on a particular {@link Scheduler}.</dd>
299 * </dl>
300 * <p>History: 2.0.8 - experimental
301 * @param predicate the function returning {@code true} to keep a value or {@code false} to drop a value
302 * @param errorHandler the enumeration that defines how to handle errors thrown
303 * from the {@code predicate}
304 * @return the new {@code ParallelFlowable} instance
305 * @throws NullPointerException if {@code predicate} or {@code errorHandler} is {@code null}
306 * @since 2.2
307 */
308 @CheckReturnValue
309 @NonNull
310 @SchedulerSupport(SchedulerSupport.NONE)
311 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
312 public final ParallelFlowable<T> filter(@NonNull Predicate<? super T> predicate, @NonNull ParallelFailureHandling errorHandler) {
313 Objects.requireNonNull(predicate, "predicate is null");
314 Objects.requireNonNull(errorHandler, "errorHandler is null");
315 return RxJavaPlugins.onAssembly(new ParallelFilterTry<>(this, predicate, errorHandler));
316 }
317
318 /**
319 * Filters the source values on each 'rail' and
320 * handles errors based on the returned value by the handler function.
321 * <p>
322 * Note that the same predicate may be called from multiple threads concurrently.
323 * <dl>
324 * <dt><b>Backpressure:</b></dt>
325 * <dd>The operator is a pass-through for backpressure and the behavior
326 * is determined by the upstream and downstream rail behaviors.</dd>
327 * <dt><b>Scheduler:</b></dt>
328 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
329 * </dl>
330 * <p>History: 2.0.8 - experimental
331 * @param predicate the function returning {@code true} to keep a value or {@code false} to drop a value
332 * @param errorHandler the function called with the current repeat count and
333 * failure {@link Throwable} and should return one of the {@link ParallelFailureHandling}
334 * enumeration values to indicate how to proceed.
335 * @return the new {@code ParallelFlowable} instance
336 * @throws NullPointerException if {@code predicate} or {@code errorHandler} is {@code null}
337 * @since 2.2
338 */
339 @CheckReturnValue
340 @NonNull
341 @SchedulerSupport(SchedulerSupport.NONE)
342 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
343 public final ParallelFlowable<T> filter(@NonNull Predicate<? super T> predicate, @NonNull BiFunction<? super Long, ? super Throwable, ParallelFailureHandling> errorHandler) {
344 Objects.requireNonNull(predicate, "predicate is null");
345 Objects.requireNonNull(errorHandler, "errorHandler is null");
346 return RxJavaPlugins.onAssembly(new ParallelFilterTry<>(this, predicate, errorHandler));
347 }
348
349 /**
350 * Specifies where each 'rail' will observe its incoming values, specified via a {@link Scheduler}, with
351 * no work-stealing and default prefetch amount.
352 * <p>
353 * This operator uses the default prefetch size returned by {@link Flowable#bufferSize()}.
354 * <p>
355 * The operator will call {@link Scheduler#createWorker()} as many
356 * times as this {@code ParallelFlowable}'s parallelism level is.
357 * <p>
358 * No assumptions are made about the {@code Scheduler}'s parallelism level,
359 * if the {@code Scheduler}'s parallelism level is lower than the {@code ParallelFlowable}'s,
360 * some rails may end up on the same thread/worker.
361 * <p>
362 * This operator doesn't require the {@code Scheduler} to be trampolining as it
363 * does its own built-in trampolining logic.
364 * <dl>
365 * <dt><b>Backpressure:</b></dt>
366 * <dd>The operator honors the backpressure of the parallel rails and
367 * requests {@link Flowable#bufferSize} amount from the upstream, followed
368 * by 75% of that amount requested after every 75% received.</dd>
369 * <dt><b>Scheduler:</b></dt>
370 * <dd>{@code runOn} drains the upstream rails on the specified {@code Scheduler}'s
371 * {@link io.reactivex.rxjava3.core.Scheduler.Worker Worker}s.</dd>
372 * </dl>
373 *
374 * @param scheduler the scheduler to use
375 * @return the new {@code ParallelFlowable} instance
376 * @throws NullPointerException if {@code scheduler} is {@code null}
377 */
378 @CheckReturnValue
379 @NonNull
380 @BackpressureSupport(BackpressureKind.FULL)
381 @SchedulerSupport(SchedulerSupport.CUSTOM)
382 public final ParallelFlowable<T> runOn(@NonNull Scheduler scheduler) {
383 return runOn(scheduler, Flowable.bufferSize());
384 }
385
386 /**
387 * Specifies where each 'rail' will observe its incoming values, specified via a {@link Scheduler}, with
388 * possibly work-stealing and a given prefetch amount.
389 * <p>
390 * This operator uses the default prefetch size returned by {@link Flowable#bufferSize()}.
391 * <p>
392 * The operator will call {@link Scheduler#createWorker()} as many
393 * times as this {@code ParallelFlowable}'s parallelism level is.
394 * <p>
395 * No assumptions are made about the {@code Scheduler}'s parallelism level,
396 * if the {@code Scheduler}'s parallelism level is lower than the {@code ParallelFlowable}'s,
397 * some rails may end up on the same thread/worker.
398 * <p>
399 * This operator doesn't require the {@code Scheduler} to be trampolining as it
400 * does its own built-in trampolining logic.
401 * <dl>
402 * <dt><b>Backpressure:</b></dt>
403 * <dd>The operator honors the backpressure of the parallel rails and
404 * requests the {@code prefetch} amount from the upstream, followed
405 * by 75% of that amount requested after every 75% received.</dd>
406 * <dt><b>Scheduler:</b></dt>
407 * <dd>{@code runOn} drains the upstream rails on the specified {@code Scheduler}'s
408 * {@link io.reactivex.rxjava3.core.Scheduler.Worker Worker}s.</dd>
409 * </dl>
410 *
411 * @param scheduler the scheduler to use
412 * that rail's worker has run out of work.
413 * @param prefetch the number of values to request on each 'rail' from the source
414 * @return the new {@code ParallelFlowable} instance
415 * @throws NullPointerException if {@code scheduler} is {@code null}
416 * @throws IllegalArgumentException if {@code prefetch} is non-positive
417 */
418 @CheckReturnValue
419 @NonNull
420 @BackpressureSupport(BackpressureKind.FULL)
421 @SchedulerSupport(SchedulerSupport.CUSTOM)
422 public final ParallelFlowable<T> runOn(@NonNull Scheduler scheduler, int prefetch) {
423 Objects.requireNonNull(scheduler, "scheduler is null");
424 ObjectHelper.verifyPositive(prefetch, "prefetch");
425 return RxJavaPlugins.onAssembly(new ParallelRunOn<>(this, scheduler, prefetch));
426 }
427
428 /**
429 * Reduces all values within a 'rail' and across 'rails' with a reducer function into one
430 * {@link Flowable} sequence.
431 * <p>
432 * Note that the same reducer function may be called from multiple threads concurrently.
433 * <dl>
434 * <dt><b>Backpressure:</b></dt>
435 * <dd>The operator honors backpressure from the downstream and consumes
436 * the upstream rails in an unbounded manner (requesting {@link Long#MAX_VALUE}).</dd>
437 * <dt><b>Scheduler:</b></dt>
438 * <dd>{@code reduce} does not operate by default on a particular {@link Scheduler}.</dd>
439 * </dl>
440 * @param reducer the function to reduce two values into one.
441 * @return the new {@code Flowable} instance emitting the reduced value or empty if the current {@code ParallelFlowable} is empty
442 * @throws NullPointerException if {@code reducer} is {@code null}
443 */
444 @CheckReturnValue
445 @NonNull
446 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
447 @SchedulerSupport(SchedulerSupport.NONE)
448 public final Flowable<T> reduce(@NonNull BiFunction<T, T, T> reducer) {
449 Objects.requireNonNull(reducer, "reducer is null");
450 return RxJavaPlugins.onAssembly(new ParallelReduceFull<>(this, reducer));
451 }
452
453 /**
454 * Reduces all values within a 'rail' to a single value (with a possibly different type) via
455 * a reducer function that is initialized on each rail from an {@code initialSupplier} value.
456 * <p>
457 * Note that the same mapper function may be called from multiple threads concurrently.
458 * <dl>
459 * <dt><b>Backpressure:</b></dt>
460 * <dd>The operator honors backpressure from the downstream rails and consumes
461 * the upstream rails in an unbounded manner (requesting {@link Long#MAX_VALUE}).</dd>
462 * <dt><b>Scheduler:</b></dt>
463 * <dd>{@code reduce} does not operate by default on a particular {@link Scheduler}.</dd>
464 * </dl>
465 * @param <R> the reduced output type
466 * @param initialSupplier the supplier for the initial value
467 * @param reducer the function to reduce a previous output of reduce (or the initial value supplied)
468 * with a current source value.
469 * @return the new {@code ParallelFlowable} instance
470 * @throws NullPointerException if {@code initialSupplier} or {@code reducer} is {@code null}
471 */
472 @CheckReturnValue
473 @NonNull
474 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
475 @SchedulerSupport(SchedulerSupport.NONE)
476 public final <@NonNull R> ParallelFlowable<R> reduce(@NonNull Supplier<R> initialSupplier, @NonNull BiFunction<R, ? super T, R> reducer) {
477 Objects.requireNonNull(initialSupplier, "initialSupplier is null");
478 Objects.requireNonNull(reducer, "reducer is null");
479 return RxJavaPlugins.onAssembly(new ParallelReduce<>(this, initialSupplier, reducer));
480 }
481
482 /**
483 * Merges the values from each 'rail' in a round-robin or same-order fashion and
484 * exposes it as a regular {@link Flowable} sequence, running with a default prefetch value
485 * for the rails.
486 * <p>
487 * This operator uses the default prefetch size returned by {@code Flowable.bufferSize()}.
488 * <img width="640" height="602" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/parallelflowable.sequential.png" alt="">
489 * <dl>
490 * <dt><b>Backpressure:</b></dt>
491 * <dd>The operator honors backpressure from the downstream and
492 * requests {@link Flowable#bufferSize()} amount from each rail, then
493 * requests from each rail 75% of this amount after 75% received.</dd>
494 * <dt><b>Scheduler:</b></dt>
495 * <dd>{@code sequential} does not operate by default on a particular {@link Scheduler}.</dd>
496 * </dl>
497 * @return the new {@code Flowable} instance
498 * @see ParallelFlowable#sequential(int)
499 * @see ParallelFlowable#sequentialDelayError()
500 */
501 @BackpressureSupport(BackpressureKind.FULL)
502 @SchedulerSupport(SchedulerSupport.NONE)
503 @CheckReturnValue
504 @NonNull
505 public final Flowable<T> sequential() {
506 return sequential(Flowable.bufferSize());
507 }
508
509 /**
510 * Merges the values from each 'rail' in a round-robin or same-order fashion and
511 * exposes it as a regular {@link Flowable} sequence, running with a give prefetch value
512 * for the rails.
513 * <img width="640" height="602" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/parallelflowable.sequential.png" alt="">
514 * <dl>
515 * <dt><b>Backpressure:</b></dt>
516 * <dd>The operator honors backpressure from the downstream and
517 * requests the {@code prefetch} amount from each rail, then
518 * requests from each rail 75% of this amount after 75% received.</dd>
519 * <dt><b>Scheduler:</b></dt>
520 * <dd>{@code sequential} does not operate by default on a particular {@link Scheduler}.</dd>
521 * </dl>
522 * @param prefetch the prefetch amount to use for each rail
523 * @return the new {@code Flowable} instance
524 * @throws IllegalArgumentException if {@code prefetch} is non-positive
525 * @see ParallelFlowable#sequential()
526 * @see ParallelFlowable#sequentialDelayError(int)
527 */
528 @BackpressureSupport(BackpressureKind.FULL)
529 @SchedulerSupport(SchedulerSupport.NONE)
530 @CheckReturnValue
531 @NonNull
532 public final Flowable<T> sequential(int prefetch) {
533 ObjectHelper.verifyPositive(prefetch, "prefetch");
534 return RxJavaPlugins.onAssembly(new ParallelJoin<>(this, prefetch, false));
535 }
536
537 /**
538 * Merges the values from each 'rail' in a round-robin or same-order fashion and
539 * exposes it as a regular {@link Flowable} sequence, running with a default prefetch value
540 * for the rails and delaying errors from all rails till all terminate.
541 * <p>
542 * This operator uses the default prefetch size returned by {@code Flowable.bufferSize()}.
543 * <img width="640" height="602" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/parallelflowable.sequential.png" alt="">
544 * <dl>
545 * <dt><b>Backpressure:</b></dt>
546 * <dd>The operator honors backpressure from the downstream and
547 * requests {@link Flowable#bufferSize()} amount from each rail, then
548 * requests from each rail 75% of this amount after 75% received.</dd>
549 * <dt><b>Scheduler:</b></dt>
550 * <dd>{@code sequentialDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
551 * </dl>
552 * <p>History: 2.0.7 - experimental
553 * @return the new {@code Flowable} instance
554 * @see ParallelFlowable#sequentialDelayError(int)
555 * @see ParallelFlowable#sequential()
556 * @since 2.2
557 */
558 @BackpressureSupport(BackpressureKind.FULL)
559 @SchedulerSupport(SchedulerSupport.NONE)
560 @CheckReturnValue
561 @NonNull
562 public final Flowable<T> sequentialDelayError() {
563 return sequentialDelayError(Flowable.bufferSize());
564 }
565
566 /**
567 * Merges the values from each 'rail' in a round-robin or same-order fashion and
568 * exposes it as a regular {@link Flowable} sequence, running with a give prefetch value
569 * for the rails and delaying errors from all rails till all terminate.
570 * <img width="640" height="602" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/parallelflowable.sequential.png" alt="">
571 * <dl>
572 * <dt><b>Backpressure:</b></dt>
573 * <dd>The operator honors backpressure from the downstream and
574 * requests the {@code prefetch} amount from each rail, then
575 * requests from each rail 75% of this amount after 75% received.</dd>
576 * <dt><b>Scheduler:</b></dt>
577 * <dd>{@code sequentialDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
578 * </dl>
579 * <p>History: 2.0.7 - experimental
580 * @param prefetch the prefetch amount to use for each rail
581 * @return the new {@code Flowable} instance
582 * @throws IllegalArgumentException if {@code prefetch} is non-positive
583 * @see ParallelFlowable#sequential()
584 * @see ParallelFlowable#sequentialDelayError()
585 * @since 2.2
586 */
587 @BackpressureSupport(BackpressureKind.FULL)
588 @SchedulerSupport(SchedulerSupport.NONE)
589 @CheckReturnValue
590 @NonNull
591 public final Flowable<T> sequentialDelayError(int prefetch) {
592 ObjectHelper.verifyPositive(prefetch, "prefetch");
593 return RxJavaPlugins.onAssembly(new ParallelJoin<>(this, prefetch, true));
594 }
595
596 /**
597 * Sorts the 'rails' of this {@code ParallelFlowable} and returns a {@link Flowable} that sequentially
598 * picks the smallest next value from the rails.
599 * <p>
600 * This operator requires a finite source {@code ParallelFlowable}.
601 * <dl>
602 * <dt><b>Backpressure:</b></dt>
603 * <dd>The operator honors backpressure from the downstream and
604 * consumes the upstream rails in an unbounded manner (requesting {@link Long#MAX_VALUE}).</dd>
605 * <dt><b>Scheduler:</b></dt>
606 * <dd>{@code sorted} does not operate by default on a particular {@link Scheduler}.</dd>
607 * </dl>
608 *
609 * @param comparator the comparator to use
610 * @return the new {@code Flowable} instance
611 * @throws NullPointerException if {@code comparator} is {@code null}
612 */
613 @CheckReturnValue
614 @NonNull
615 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
616 @SchedulerSupport(SchedulerSupport.NONE)
617 public final Flowable<T> sorted(@NonNull Comparator<? super T> comparator) {
618 return sorted(comparator, 16);
619 }
620
621 /**
622 * Sorts the 'rails' of this {@code ParallelFlowable} and returns a {@link Flowable} that sequentially
623 * picks the smallest next value from the rails.
624 * <p>
625 * This operator requires a finite source {@code ParallelFlowable}.
626 * <dl>
627 * <dt><b>Backpressure:</b></dt>
628 * <dd>The operator honors backpressure from the downstream and
629 * consumes the upstream rails in an unbounded manner (requesting {@link Long#MAX_VALUE}).</dd>
630 * <dt><b>Scheduler:</b></dt>
631 * <dd>{@code sorted} does not operate by default on a particular {@link Scheduler}.</dd>
632 * </dl>
633 *
634 * @param comparator the comparator to use
635 * @param capacityHint the expected number of total elements
636 * @return the new {@code Flowable} instance
637 * @throws NullPointerException if {@code comparator} is {@code null}
638 * @throws IllegalArgumentException if {@code capacityHint} is non-positive
639 */
640 @CheckReturnValue
641 @NonNull
642 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
643 @SchedulerSupport(SchedulerSupport.NONE)
644 public final Flowable<T> sorted(@NonNull Comparator<? super T> comparator, int capacityHint) {
645 Objects.requireNonNull(comparator, "comparator is null");
646 ObjectHelper.verifyPositive(capacityHint, "capacityHint");
647 int ch = capacityHint / parallelism() + 1;
648 ParallelFlowable<List<T>> railReduced = reduce(Functions.createArrayList(ch), ListAddBiConsumer.instance());
649 ParallelFlowable<List<T>> railSorted = railReduced.map(new SorterFunction<>(comparator));
650
651 return RxJavaPlugins.onAssembly(new ParallelSortedJoin<>(railSorted, comparator));
652 }
653
654 /**
655 * Sorts the 'rails' according to the comparator and returns a full sorted {@link List} as a {@link Flowable}.
656 * <p>
657 * This operator requires a finite source {@code ParallelFlowable}.
658 * <dl>
659 * <dt><b>Backpressure:</b></dt>
660 * <dd>The operator honors backpressure from the downstream and
661 * consumes the upstream rails in an unbounded manner (requesting {@link Long#MAX_VALUE}).</dd>
662 * <dt><b>Scheduler:</b></dt>
663 * <dd>{@code toSortedList} does not operate by default on a particular {@link Scheduler}.</dd>
664 * </dl>
665 *
666 * @param comparator the comparator to compare elements
667 * @return the new {@code Flowable} instance
668 * @throws NullPointerException if {@code comparator} is {@code null}
669 */
670 @CheckReturnValue
671 @NonNull
672 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
673 @SchedulerSupport(SchedulerSupport.NONE)
674 public final Flowable<List<T>> toSortedList(@NonNull Comparator<? super T> comparator) {
675 return toSortedList(comparator, 16);
676 }
677 /**
678 * Sorts the 'rails' according to the comparator and returns a full sorted {@link List} as a {@link Flowable}.
679 * <p>
680 * This operator requires a finite source {@code ParallelFlowable}.
681 * <dl>
682 * <dt><b>Backpressure:</b></dt>
683 * <dd>The operator honors backpressure from the downstream and
684 * consumes the upstream rails in an unbounded manner (requesting {@link Long#MAX_VALUE}).</dd>
685 * <dt><b>Scheduler:</b></dt>
686 * <dd>{@code toSortedList} does not operate by default on a particular {@link Scheduler}.</dd>
687 * </dl>
688 *
689 * @param comparator the comparator to compare elements
690 * @param capacityHint the expected number of total elements
691 * @return the new {@code Flowable} instance
692 * @throws NullPointerException if {@code comparator} is {@code null}
693 * @throws IllegalArgumentException if {@code capacityHint} is non-positive
694 */
695 @CheckReturnValue
696 @NonNull
697 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
698 @SchedulerSupport(SchedulerSupport.NONE)
699 public final Flowable<@NonNull List<T>> toSortedList(@NonNull Comparator<? super T> comparator, int capacityHint) {
700 Objects.requireNonNull(comparator, "comparator is null");
701 ObjectHelper.verifyPositive(capacityHint, "capacityHint");
702
703 int ch = capacityHint / parallelism() + 1;
704 ParallelFlowable<List<T>> railReduced = reduce(Functions.createArrayList(ch), ListAddBiConsumer.instance());
705 ParallelFlowable<List<T>> railSorted = railReduced.map(new SorterFunction<>(comparator));
706
707 Flowable<List<T>> merged = railSorted.reduce(new MergerBiFunction<>(comparator));
708
709 return RxJavaPlugins.onAssembly(merged);
710 }
711
712 /**
713 * Call the specified consumer with the current element passing through any 'rail'.
714 * <dl>
715 * <dt><b>Backpressure:</b></dt>
716 * <dd>The operator is a pass-through for backpressure and the behavior
717 * is determined by the upstream and downstream rail behaviors.</dd>
718 * <dt><b>Scheduler:</b></dt>
719 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
720 * </dl>
721 *
722 * @param onNext the callback
723 * @return the new {@code ParallelFlowable} instance
724 * @throws NullPointerException if {@code onNext} is {@code null}
725 */
726 @CheckReturnValue
727 @NonNull
728 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
729 @SchedulerSupport(SchedulerSupport.NONE)
730 public final ParallelFlowable<T> doOnNext(@NonNull Consumer<? super T> onNext) {
731 Objects.requireNonNull(onNext, "onNext is null");
732 return RxJavaPlugins.onAssembly(new ParallelPeek<>(this,
733 onNext,
734 Functions.emptyConsumer(),
735 Functions.emptyConsumer(),
736 Functions.EMPTY_ACTION,
737 Functions.EMPTY_ACTION,
738 Functions.emptyConsumer(),
739 Functions.EMPTY_LONG_CONSUMER,
740 Functions.EMPTY_ACTION
741 ));
742 }
743
744 /**
745 * Call the specified consumer with the current element passing through any 'rail' and
746 * handles errors based on the given {@link ParallelFailureHandling} enumeration value.
747 * <dl>
748 * <dt><b>Backpressure:</b></dt>
749 * <dd>The operator is a pass-through for backpressure and the behavior
750 * is determined by the upstream and downstream rail behaviors.</dd>
751 * <dt><b>Scheduler:</b></dt>
752 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
753 * </dl>
754 * <p>History: 2.0.8 - experimental
755 * @param onNext the callback
756 * @param errorHandler the enumeration that defines how to handle errors thrown
757 * from the {@code onNext} consumer
758 * @return the new {@code ParallelFlowable} instance
759 * @throws NullPointerException if {@code onNext} or {@code errorHandler} is {@code null}
760 * @since 2.2
761 */
762 @CheckReturnValue
763 @NonNull
764 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
765 @SchedulerSupport(SchedulerSupport.NONE)
766 public final ParallelFlowable<T> doOnNext(@NonNull Consumer<? super T> onNext, @NonNull ParallelFailureHandling errorHandler) {
767 Objects.requireNonNull(onNext, "onNext is null");
768 Objects.requireNonNull(errorHandler, "errorHandler is null");
769 return RxJavaPlugins.onAssembly(new ParallelDoOnNextTry<>(this, onNext, errorHandler));
770 }
771
772 /**
773 * Call the specified consumer with the current element passing through any 'rail' and
774 * handles errors based on the returned value by the handler function.
775 * <dl>
776 * <dt><b>Backpressure:</b></dt>
777 * <dd>The operator is a pass-through for backpressure and the behavior
778 * is determined by the upstream and downstream rail behaviors.</dd>
779 * <dt><b>Scheduler:</b></dt>
780 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
781 * </dl>
782 * <p>History: 2.0.8 - experimental
783 * @param onNext the callback
784 * @param errorHandler the function called with the current repeat count and
785 * failure {@link Throwable} and should return one of the {@link ParallelFailureHandling}
786 * enumeration values to indicate how to proceed.
787 * @return the new {@code ParallelFlowable} instance
788 * @throws NullPointerException if {@code onNext} or {@code errorHandler} is {@code null}
789 * @since 2.2
790 */
791 @CheckReturnValue
792 @NonNull
793 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
794 @SchedulerSupport(SchedulerSupport.NONE)
795 public final ParallelFlowable<T> doOnNext(@NonNull Consumer<? super T> onNext, @NonNull BiFunction<? super Long, ? super Throwable, ParallelFailureHandling> errorHandler) {
796 Objects.requireNonNull(onNext, "onNext is null");
797 Objects.requireNonNull(errorHandler, "errorHandler is null");
798 return RxJavaPlugins.onAssembly(new ParallelDoOnNextTry<>(this, onNext, errorHandler));
799 }
800
801 /**
802 * Call the specified consumer with the current element passing through any 'rail'
803 * after it has been delivered to downstream within the rail.
804 * <dl>
805 * <dt><b>Backpressure:</b></dt>
806 * <dd>The operator is a pass-through for backpressure and the behavior
807 * is determined by the upstream and downstream rail behaviors.</dd>
808 * <dt><b>Scheduler:</b></dt>
809 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
810 * </dl>
811 *
812 * @param onAfterNext the callback
813 * @return the new {@code ParallelFlowable} instance
814 * @throws NullPointerException if {@code onAfterNext} is {@code null}
815 */
816 @CheckReturnValue
817 @NonNull
818 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
819 @SchedulerSupport(SchedulerSupport.NONE)
820 public final ParallelFlowable<T> doAfterNext(@NonNull Consumer<? super T> onAfterNext) {
821 Objects.requireNonNull(onAfterNext, "onAfterNext is null");
822 return RxJavaPlugins.onAssembly(new ParallelPeek<>(this,
823 Functions.emptyConsumer(),
824 onAfterNext,
825 Functions.emptyConsumer(),
826 Functions.EMPTY_ACTION,
827 Functions.EMPTY_ACTION,
828 Functions.emptyConsumer(),
829 Functions.EMPTY_LONG_CONSUMER,
830 Functions.EMPTY_ACTION
831 ));
832 }
833
834 /**
835 * Call the specified consumer with the exception passing through any 'rail'.
836 * <dl>
837 * <dt><b>Backpressure:</b></dt>
838 * <dd>The operator is a pass-through for backpressure and the behavior
839 * is determined by the upstream and downstream rail behaviors.</dd>
840 * <dt><b>Scheduler:</b></dt>
841 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
842 * </dl>
843 *
844 * @param onError the callback
845 * @return the new {@code ParallelFlowable} instance
846 * @throws NullPointerException if {@code onError} is {@code null}
847 */
848 @CheckReturnValue
849 @NonNull
850 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
851 @SchedulerSupport(SchedulerSupport.NONE)
852 public final ParallelFlowable<T> doOnError(@NonNull Consumer<? super Throwable> onError) {
853 Objects.requireNonNull(onError, "onError is null");
854 return RxJavaPlugins.onAssembly(new ParallelPeek<>(this,
855 Functions.emptyConsumer(),
856 Functions.emptyConsumer(),
857 onError,
858 Functions.EMPTY_ACTION,
859 Functions.EMPTY_ACTION,
860 Functions.emptyConsumer(),
861 Functions.EMPTY_LONG_CONSUMER,
862 Functions.EMPTY_ACTION
863 ));
864 }
865
866 /**
867 * Run the specified {@link Action} when a 'rail' completes.
868 * <dl>
869 * <dt><b>Backpressure:</b></dt>
870 * <dd>The operator is a pass-through for backpressure and the behavior
871 * is determined by the upstream and downstream rail behaviors.</dd>
872 * <dt><b>Scheduler:</b></dt>
873 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
874 * </dl>
875 *
876 * @param onComplete the callback
877 * @return the new {@code ParallelFlowable} instance
878 * @throws NullPointerException if {@code onComplete} is {@code null}
879 */
880 @CheckReturnValue
881 @NonNull
882 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
883 @SchedulerSupport(SchedulerSupport.NONE)
884 public final ParallelFlowable<T> doOnComplete(@NonNull Action onComplete) {
885 Objects.requireNonNull(onComplete, "onComplete is null");
886 return RxJavaPlugins.onAssembly(new ParallelPeek<>(this,
887 Functions.emptyConsumer(),
888 Functions.emptyConsumer(),
889 Functions.emptyConsumer(),
890 onComplete,
891 Functions.EMPTY_ACTION,
892 Functions.emptyConsumer(),
893 Functions.EMPTY_LONG_CONSUMER,
894 Functions.EMPTY_ACTION
895 ));
896 }
897
898 /**
899 * Run the specified {@link Action} when a 'rail' completes or signals an error.
900 * <dl>
901 * <dt><b>Backpressure:</b></dt>
902 * <dd>The operator is a pass-through for backpressure and the behavior
903 * is determined by the upstream and downstream rail behaviors.</dd>
904 * <dt><b>Scheduler:</b></dt>
905 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
906 * </dl>
907 *
908 * @param onAfterTerminate the callback
909 * @return the new {@code ParallelFlowable} instance
910 * @throws NullPointerException if {@code onAfterTerminate} is {@code null}
911 */
912 @CheckReturnValue
913 @NonNull
914 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
915 @SchedulerSupport(SchedulerSupport.NONE)
916 public final ParallelFlowable<T> doAfterTerminated(@NonNull Action onAfterTerminate) {
917 Objects.requireNonNull(onAfterTerminate, "onAfterTerminate is null");
918 return RxJavaPlugins.onAssembly(new ParallelPeek<>(this,
919 Functions.emptyConsumer(),
920 Functions.emptyConsumer(),
921 Functions.emptyConsumer(),
922 Functions.EMPTY_ACTION,
923 onAfterTerminate,
924 Functions.emptyConsumer(),
925 Functions.EMPTY_LONG_CONSUMER,
926 Functions.EMPTY_ACTION
927 ));
928 }
929
930 /**
931 * Call the specified callback when a 'rail' receives a {@link Subscription} from its upstream.
932 * <dl>
933 * <dt><b>Backpressure:</b></dt>
934 * <dd>The operator is a pass-through for backpressure and the behavior
935 * is determined by the upstream and downstream rail behaviors.</dd>
936 * <dt><b>Scheduler:</b></dt>
937 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
938 * </dl>
939 *
940 * @param onSubscribe the callback
941 * @return the new {@code ParallelFlowable} instance
942 * @throws NullPointerException if {@code onSubscribe} is {@code null}
943 */
944 @CheckReturnValue
945 @NonNull
946 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
947 @SchedulerSupport(SchedulerSupport.NONE)
948 public final ParallelFlowable<T> doOnSubscribe(@NonNull Consumer<? super Subscription> onSubscribe) {
949 Objects.requireNonNull(onSubscribe, "onSubscribe is null");
950 return RxJavaPlugins.onAssembly(new ParallelPeek<>(this,
951 Functions.emptyConsumer(),
952 Functions.emptyConsumer(),
953 Functions.emptyConsumer(),
954 Functions.EMPTY_ACTION,
955 Functions.EMPTY_ACTION,
956 onSubscribe,
957 Functions.EMPTY_LONG_CONSUMER,
958 Functions.EMPTY_ACTION
959 ));
960 }
961
962 /**
963 * Call the specified consumer with the request amount if any rail receives a request.
964 * <dl>
965 * <dt><b>Backpressure:</b></dt>
966 * <dd>The operator is a pass-through for backpressure and the behavior
967 * is determined by the upstream and downstream rail behaviors.</dd>
968 * <dt><b>Scheduler:</b></dt>
969 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
970 * </dl>
971 *
972 * @param onRequest the callback
973 * @return the new {@code ParallelFlowable} instance
974 * @throws NullPointerException if {@code onRequest} is {@code null}
975 */
976 @CheckReturnValue
977 @NonNull
978 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
979 @SchedulerSupport(SchedulerSupport.NONE)
980 public final ParallelFlowable<T> doOnRequest(@NonNull LongConsumer onRequest) {
981 Objects.requireNonNull(onRequest, "onRequest is null");
982 return RxJavaPlugins.onAssembly(new ParallelPeek<>(this,
983 Functions.emptyConsumer(),
984 Functions.emptyConsumer(),
985 Functions.emptyConsumer(),
986 Functions.EMPTY_ACTION,
987 Functions.EMPTY_ACTION,
988 Functions.emptyConsumer(),
989 onRequest,
990 Functions.EMPTY_ACTION
991 ));
992 }
993
994 /**
995 * Run the specified {@link Action} when a 'rail' receives a cancellation.
996 * <dl>
997 * <dt><b>Backpressure:</b></dt>
998 * <dd>The operator is a pass-through for backpressure and the behavior
999 * is determined by the upstream and downstream rail behaviors.</dd>
1000 * <dt><b>Scheduler:</b></dt>
1001 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
1002 * </dl>
1003 *
1004 * @param onCancel the callback
1005 * @return the new {@code ParallelFlowable} instance
1006 * @throws NullPointerException if {@code onCancel} is {@code null}
1007 */
1008 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
1009 @SchedulerSupport(SchedulerSupport.NONE)
1010 @CheckReturnValue
1011 @NonNull
1012 public final ParallelFlowable<T> doOnCancel(@NonNull Action onCancel) {
1013 Objects.requireNonNull(onCancel, "onCancel is null");
1014 return RxJavaPlugins.onAssembly(new ParallelPeek<>(this,
1015 Functions.emptyConsumer(),
1016 Functions.emptyConsumer(),
1017 Functions.emptyConsumer(),
1018 Functions.EMPTY_ACTION,
1019 Functions.EMPTY_ACTION,
1020 Functions.emptyConsumer(),
1021 Functions.EMPTY_LONG_CONSUMER,
1022 onCancel
1023 ));
1024 }
1025
1026 /**
1027 * Collect the elements in each rail into a collection supplied via a {@code collectionSupplier}
1028 * and collected into with a collector action, emitting the collection at the end.
1029 * <dl>
1030 * <dt><b>Backpressure:</b></dt>
1031 * <dd>The operator honors backpressure from the downstream rails and
1032 * consumes the upstream rails in an unbounded manner (requesting {@link Long#MAX_VALUE}).</dd>
1033 * <dt><b>Scheduler:</b></dt>
1034 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
1035 * </dl>
1036 *
1037 * @param <C> the collection type
1038 * @param collectionSupplier the supplier of the collection in each rail
1039 * @param collector the collector, taking the per-rail collection and the current item
1040 * @return the new {@code ParallelFlowable} instance
1041 * @throws NullPointerException if {@code collectionSupplier} or {@code collector} is {@code null}
1042 */
1043 @CheckReturnValue
1044 @NonNull
1045 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
1046 @SchedulerSupport(SchedulerSupport.NONE)
1047 public final <@NonNull C> ParallelFlowable<C> collect(@NonNull Supplier<? extends C> collectionSupplier, @NonNull BiConsumer<? super C, ? super T> collector) {
1048 Objects.requireNonNull(collectionSupplier, "collectionSupplier is null");
1049 Objects.requireNonNull(collector, "collector is null");
1050 return RxJavaPlugins.onAssembly(new ParallelCollect<>(this, collectionSupplier, collector));
1051 }
1052
1053 /**
1054 * Wraps multiple {@link Publisher}s into a {@code ParallelFlowable} which runs them
1055 * in parallel and unordered.
1056 * <dl>
1057 * <dt><b>Backpressure:</b></dt>
1058 * <dd>The operator is a pass-through for backpressure and the behavior
1059 * is determined by the upstream and downstream rail behaviors.</dd>
1060 * <dt><b>Scheduler:</b></dt>
1061 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
1062 * </dl>
1063 *
1064 * @param <T> the value type
1065 * @param publishers the array of publishers
1066 * @return the new {@code ParallelFlowable} instance
1067 * @throws NullPointerException if {@code publishers} is {@code null}
1068 * @throws IllegalArgumentException if {@code publishers} is an empty array
1069 */
1070 @CheckReturnValue
1071 @NonNull
1072 @SafeVarargs
1073 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
1074 @SchedulerSupport(SchedulerSupport.NONE)
1075 public static <@NonNull T> ParallelFlowable<T> fromArray(@NonNull Publisher<T>... publishers) {
1076 Objects.requireNonNull(publishers, "publishers is null");
1077 if (publishers.length == 0) {
1078 throw new IllegalArgumentException("Zero publishers not supported");
1079 }
1080 return RxJavaPlugins.onAssembly(new ParallelFromArray<>(publishers));
1081 }
1082
1083 /**
1084 * Calls the specified converter function during assembly time and returns its resulting value.
1085 * <p>
1086 * This allows fluent conversion to any other type.
1087 * <dl>
1088 * <dt><b>Backpressure:</b></dt>
1089 * <dd>The operator is a pass-through for backpressure and the behavior
1090 * is determined by how the converter function composes over the upstream source.</dd>
1091 * <dt><b>Scheduler:</b></dt>
1092 * <dd>{@code to} does not operate by default on a particular {@link Scheduler}.</dd>
1093 * </dl>
1094 * <p>History: 2.1.7 - experimental
1095 * @param <R> the resulting object type
1096 * @param converter the function that receives the current {@code ParallelFlowable} instance and returns a value
1097 * @return the converted value
1098 * @throws NullPointerException if {@code converter} is {@code null}
1099 * @since 2.2
1100 */
1101 @CheckReturnValue
1102 @NonNull
1103 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
1104 @SchedulerSupport(SchedulerSupport.NONE)
1105 public final <@NonNull R> R to(@NonNull ParallelFlowableConverter<T, R> converter) {
1106 return Objects.requireNonNull(converter, "converter is null").apply(this);
1107 }
1108
1109 /**
1110 * Allows composing operators, in assembly time, on top of this {@code ParallelFlowable}
1111 * and returns another {@code ParallelFlowable} with composed features.
1112 * <dl>
1113 * <dt><b>Backpressure:</b></dt>
1114 * <dd>The operator is a pass-through for backpressure and the behavior
1115 * is determined by how the converter function composes over the upstream source.</dd>
1116 * <dt><b>Scheduler:</b></dt>
1117 * <dd>{@code compose} does not operate by default on a particular {@link Scheduler}.</dd>
1118 * </dl>
1119 *
1120 * @param <U> the output value type
1121 * @param composer the composer function from {@code ParallelFlowable} (this) to another {@code ParallelFlowable}
1122 * @return the {@code ParallelFlowable} returned by the function
1123 * @throws NullPointerException if {@code composer} is {@code null}
1124 */
1125 @CheckReturnValue
1126 @NonNull
1127 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
1128 @SchedulerSupport(SchedulerSupport.NONE)
1129 public final <@NonNull U> ParallelFlowable<U> compose(@NonNull ParallelTransformer<T, U> composer) {
1130 return RxJavaPlugins.onAssembly(Objects.requireNonNull(composer, "composer is null").apply(this));
1131 }
1132
1133 /**
1134 * Generates and flattens {@link Publisher}s on each 'rail'.
1135 * <p>
1136 * The errors are not delayed and uses unbounded concurrency along with default inner prefetch.
1137 * <dl>
1138 * <dt><b>Backpressure:</b></dt>
1139 * <dd>The operator honors backpressure from the downstream rails and
1140 * requests {@link Flowable#bufferSize()} amount from each rail upfront
1141 * and keeps requesting as many items per rail as many inner sources on
1142 * that rail completed. The inner sources are requested {@link Flowable#bufferSize()}
1143 * amount upfront, then 75% of this amount requested after 75% received.</dd>
1144 * <dt><b>Scheduler:</b></dt>
1145 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
1146 * </dl>
1147 *
1148 * @param <R> the result type
1149 * @param mapper the function to map each rail's value into a {@code Publisher}
1150 * @return the new {@code ParallelFlowable} instance
1151 * @throws NullPointerException if {@code mapper} is {@code null}
1152 */
1153 @CheckReturnValue
1154 @NonNull
1155 @BackpressureSupport(BackpressureKind.FULL)
1156 @SchedulerSupport(SchedulerSupport.NONE)
1157 public final <@NonNull R> ParallelFlowable<R> flatMap(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper) {
1158 return flatMap(mapper, false, Flowable.bufferSize(), Flowable.bufferSize());
1159 }
1160
1161 /**
1162 * Generates and flattens {@link Publisher}s on each 'rail', optionally delaying errors.
1163 * <p>
1164 * It uses unbounded concurrency along with default inner prefetch.
1165 * <dl>
1166 * <dt><b>Backpressure:</b></dt>
1167 * <dd>The operator honors backpressure from the downstream rails and
1168 * requests {@link Flowable#bufferSize()} amount from each rail upfront
1169 * and keeps requesting as many items per rail as many inner sources on
1170 * that rail completed. The inner sources are requested {@link Flowable#bufferSize()}
1171 * amount upfront, then 75% of this amount requested after 75% received.
1172 * </dd>
1173 * <dt><b>Scheduler:</b></dt>
1174 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
1175 * </dl>
1176 *
1177 * @param <R> the result type
1178 * @param mapper the function to map each rail's value into a {@code Publisher}
1179 * @param delayError should the errors from the main and the inner sources delayed till everybody terminates?
1180 * @return the new {@code ParallelFlowable} instance
1181 * @throws NullPointerException if {@code mapper} is {@code null}
1182 */
1183 @CheckReturnValue
1184 @NonNull
1185 @BackpressureSupport(BackpressureKind.FULL)
1186 @SchedulerSupport(SchedulerSupport.NONE)
1187 public final <@NonNull R> ParallelFlowable<R> flatMap(
1188 @NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper, boolean delayError) {
1189 return flatMap(mapper, delayError, Flowable.bufferSize(), Flowable.bufferSize());
1190 }
1191
1192 /**
1193 * Generates and flattens {@link Publisher}s on each 'rail', optionally delaying errors
1194 * and having a total number of simultaneous subscriptions to the inner {@code Publisher}s.
1195 * <p>
1196 * It uses a default inner prefetch.
1197 * <dl>
1198 * <dt><b>Backpressure:</b></dt>
1199 * <dd>The operator honors backpressure from the downstream rails and
1200 * requests {@code maxConcurrency} amount from each rail upfront
1201 * and keeps requesting as many items per rail as many inner sources on
1202 * that rail completed. The inner sources are requested {@link Flowable#bufferSize()}
1203 * amount upfront, then 75% of this amount requested after 75% received.
1204 * </dd>
1205 * <dt><b>Scheduler:</b></dt>
1206 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
1207 * </dl>
1208 *
1209 * @param <R> the result type
1210 * @param mapper the function to map each rail's value into a {@code Publisher}
1211 * @param delayError should the errors from the main and the inner sources delayed till everybody terminates?
1212 * @param maxConcurrency the maximum number of simultaneous subscriptions to the generated inner {@code Publisher}s
1213 * @return the new {@code ParallelFlowable} instance
1214 * @throws NullPointerException if {@code mapper} is {@code null}
1215 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
1216 */
1217 @CheckReturnValue
1218 @NonNull
1219 @BackpressureSupport(BackpressureKind.FULL)
1220 @SchedulerSupport(SchedulerSupport.NONE)
1221 public final <@NonNull R> ParallelFlowable<R> flatMap(
1222 @NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper, boolean delayError, int maxConcurrency) {
1223 return flatMap(mapper, delayError, maxConcurrency, Flowable.bufferSize());
1224 }
1225
1226 /**
1227 * Generates and flattens {@link Publisher}s on each 'rail', optionally delaying errors,
1228 * having a total number of simultaneous subscriptions to the inner {@code Publisher}s
1229 * and using the given prefetch amount for the inner {@code Publisher}s.
1230 * <dl>
1231 * <dt><b>Backpressure:</b></dt>
1232 * <dd>The operator honors backpressure from the downstream rails and
1233 * requests {@code maxConcurrency} amount from each rail upfront
1234 * and keeps requesting as many items per rail as many inner sources on
1235 * that rail completed. The inner sources are requested the {@code prefetch}
1236 * amount upfront, then 75% of this amount requested after 75% received.
1237 * </dd>
1238 * <dt><b>Scheduler:</b></dt>
1239 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
1240 * </dl>
1241 *
1242 * @param <R> the result type
1243 * @param mapper the function to map each rail's value into a {@code Publisher}
1244 * @param delayError should the errors from the main and the inner sources delayed till everybody terminates?
1245 * @param maxConcurrency the maximum number of simultaneous subscriptions to the generated inner {@code Publisher}s
1246 * @param prefetch the number of items to prefetch from each inner {@code Publisher}
1247 * @return the new {@code ParallelFlowable} instance
1248 * @throws NullPointerException if {@code mapper} is {@code null}
1249 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code prefetch} is non-positive
1250 */
1251 @CheckReturnValue
1252 @NonNull
1253 @BackpressureSupport(BackpressureKind.FULL)
1254 @SchedulerSupport(SchedulerSupport.NONE)
1255 public final <@NonNull R> ParallelFlowable<R> flatMap(
1256 @NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper,
1257 boolean delayError, int maxConcurrency, int prefetch) {
1258 Objects.requireNonNull(mapper, "mapper is null");
1259 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
1260 ObjectHelper.verifyPositive(prefetch, "prefetch");
1261 return RxJavaPlugins.onAssembly(new ParallelFlatMap<>(this, mapper, delayError, maxConcurrency, prefetch));
1262 }
1263
1264 /**
1265 * Generates and concatenates {@link Publisher}s on each 'rail', signalling errors immediately
1266 * and generating 2 publishers upfront.
1267 * <dl>
1268 * <dt><b>Backpressure:</b></dt>
1269 * <dd>The operator honors backpressure from the downstream rails and
1270 * requests 2 from each rail upfront and keeps requesting 1 when the inner source complete.
1271 * Requests for the inner sources are determined by the downstream rails'
1272 * backpressure behavior.</dd>
1273 * <dt><b>Scheduler:</b></dt>
1274 * <dd>{@code concatMap} does not operate by default on a particular {@link Scheduler}.</dd>
1275 * </dl>
1276 *
1277 * @param <R> the result type
1278 * @param mapper the function to map each rail's value into a {@code Publisher}
1279 * source and the inner {@code Publisher}s (immediate, boundary, end)
1280 * @return the new {@code ParallelFlowable} instance
1281 * @throws NullPointerException if {@code mapper} is {@code null}
1282 */
1283 @CheckReturnValue
1284 @NonNull
1285 @BackpressureSupport(BackpressureKind.FULL)
1286 @SchedulerSupport(SchedulerSupport.NONE)
1287 public final <@NonNull R> ParallelFlowable<R> concatMap(
1288 @NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper) {
1289 return concatMap(mapper, 2);
1290 }
1291
1292 /**
1293 * Generates and concatenates {@link Publisher}s on each 'rail', signalling errors immediately
1294 * and using the given prefetch amount for generating {@code Publisher}s upfront.
1295 * <dl>
1296 * <dt><b>Backpressure:</b></dt>
1297 * <dd>The operator honors backpressure from the downstream rails and
1298 * requests the {@code prefetch} amount from each rail upfront and keeps
1299 * requesting 75% of this amount after 75% received and the inner sources completed.
1300 * Requests for the inner sources are determined by the downstream rails'
1301 * backpressure behavior.</dd>
1302 * <dt><b>Scheduler:</b></dt>
1303 * <dd>{@code concatMap} does not operate by default on a particular {@link Scheduler}.</dd>
1304 * </dl>
1305 *
1306 * @param <R> the result type
1307 * @param mapper the function to map each rail's value into a {@code Publisher}
1308 * @param prefetch the number of items to prefetch from each inner {@code Publisher}
1309 * source and the inner {@code Publisher}s (immediate, boundary, end)
1310 * @return the new {@code ParallelFlowable} instance
1311 * @throws NullPointerException if {@code mapper} is {@code null}
1312 * @throws IllegalArgumentException if {@code prefetch} is non-positive
1313 */
1314 @CheckReturnValue
1315 @NonNull
1316 @BackpressureSupport(BackpressureKind.FULL)
1317 @SchedulerSupport(SchedulerSupport.NONE)
1318 public final <@NonNull R> ParallelFlowable<R> concatMap(
1319 @NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper,
1320 int prefetch) {
1321 Objects.requireNonNull(mapper, "mapper is null");
1322 ObjectHelper.verifyPositive(prefetch, "prefetch");
1323 return RxJavaPlugins.onAssembly(new ParallelConcatMap<>(this, mapper, prefetch, ErrorMode.IMMEDIATE));
1324 }
1325
1326 /**
1327 * Generates and concatenates {@link Publisher}s on each 'rail', optionally delaying errors
1328 * and generating 2 publishers upfront.
1329 * <dl>
1330 * <dt><b>Backpressure:</b></dt>
1331 * <dd>The operator honors backpressure from the downstream rails and
1332 * requests 2 from each rail upfront and keeps requesting 1 when the inner source complete.
1333 * Requests for the inner sources are determined by the downstream rails'
1334 * backpressure behavior.</dd>
1335 * <dt><b>Scheduler:</b></dt>
1336 * <dd>{@code concatMap} does not operate by default on a particular {@link Scheduler}.</dd>
1337 * </dl>
1338 *
1339 * @param <R> the result type
1340 * @param mapper the function to map each rail's value into a {@code Publisher}
1341 * @param tillTheEnd if {@code true}, all errors from the upstream and inner {@code Publisher}s are delayed
1342 * till all of them terminate, if {@code false}, the error is emitted when an inner {@code Publisher} terminates.
1343 * source and the inner {@code Publisher}s (immediate, boundary, end)
1344 * @return the new {@code ParallelFlowable} instance
1345 * @throws NullPointerException if {@code mapper} is {@code null}
1346 */
1347 @CheckReturnValue
1348 @NonNull
1349 @BackpressureSupport(BackpressureKind.FULL)
1350 @SchedulerSupport(SchedulerSupport.NONE)
1351 public final <@NonNull R> ParallelFlowable<R> concatMapDelayError(
1352 @NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper,
1353 boolean tillTheEnd) {
1354 return concatMapDelayError(mapper, 2, tillTheEnd);
1355 }
1356
1357 /**
1358 * Generates and concatenates {@link Publisher}s on each 'rail', optionally delaying errors
1359 * and using the given prefetch amount for generating {@code Publisher}s upfront.
1360 * <dl>
1361 * <dt><b>Backpressure:</b></dt>
1362 * <dd>The operator honors backpressure from the downstream rails and
1363 * requests the {@code prefetch} amount from each rail upfront and keeps
1364 * requesting 75% of this amount after 75% received and the inner sources completed.
1365 * Requests for the inner sources are determined by the downstream rails'
1366 * backpressure behavior.</dd>
1367 * <dt><b>Scheduler:</b></dt>
1368 * <dd>{@code concatMap} does not operate by default on a particular {@link Scheduler}.</dd>
1369 * </dl>
1370 *
1371 * @param <R> the result type
1372 * @param mapper the function to map each rail's value into a {@code Publisher}
1373 * @param prefetch the number of items to prefetch from each inner {@code Publisher}
1374 * @param tillTheEnd if {@code true}, all errors from the upstream and inner {@code Publisher}s are delayed
1375 * till all of them terminate, if {@code false}, the error is emitted when an inner {@code Publisher} terminates.
1376 * @return the new {@code ParallelFlowable} instance
1377 * @throws NullPointerException if {@code mapper} is {@code null}
1378 * @throws IllegalArgumentException if {@code prefetch} is non-positive
1379 */
1380 @CheckReturnValue
1381 @NonNull
1382 @BackpressureSupport(BackpressureKind.FULL)
1383 @SchedulerSupport(SchedulerSupport.NONE)
1384 public final <@NonNull R> ParallelFlowable<R> concatMapDelayError(
1385 @NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper,
1386 int prefetch, boolean tillTheEnd) {
1387 Objects.requireNonNull(mapper, "mapper is null");
1388 ObjectHelper.verifyPositive(prefetch, "prefetch");
1389 return RxJavaPlugins.onAssembly(new ParallelConcatMap<>(
1390 this, mapper, prefetch, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY));
1391 }
1392
1393 /**
1394 * Returns a {@code ParallelFlowable} that merges each item emitted by the source on each rail with the values in an
1395 * {@link Iterable} corresponding to that item that is generated by a selector.
1396 * <p>
1397 * <img width="640" height="342" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapIterable.f.png" alt="">
1398 * <dl>
1399 * <dt><b>Backpressure:</b></dt>
1400 * <dd>The operator honors backpressure from each downstream rail. The source {@code ParallelFlowable}s is
1401 * expected to honor backpressure as well. If the source {@code ParallelFlowable} violates the rule, the operator will
1402 * signal a {@link MissingBackpressureException}.</dd>
1403 * <dt><b>Scheduler:</b></dt>
1404 * <dd>{@code flatMapIterable} does not operate by default on a particular {@link Scheduler}.</dd>
1405 * </dl>
1406 *
1407 * @param <U>
1408 * the type of item emitted by the resulting {@code Iterable}
1409 * @param mapper
1410 * a function that returns an {@code Iterable} sequence of values for when given an item emitted by the
1411 * source {@code ParallelFlowable}
1412 * @return the new {@code ParallelFlowable} instance
1413 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
1414 * @see #flatMapStream(Function)
1415 * @since 3.0.0
1416 * @throws NullPointerException if {@code mapper} is {@code null}
1417 */
1418 @CheckReturnValue
1419 @BackpressureSupport(BackpressureKind.FULL)
1420 @SchedulerSupport(SchedulerSupport.NONE)
1421 @NonNull
1422 public final <@NonNull U> ParallelFlowable<U> flatMapIterable(@NonNull Function<? super T, @NonNull ? extends Iterable<? extends U>> mapper) {
1423 return flatMapIterable(mapper, Flowable.bufferSize());
1424 }
1425
1426 /**
1427 * Returns a {@code ParallelFlowable} that merges each item emitted by the source {@code ParallelFlowable} with the values in an
1428 * {@link Iterable} corresponding to that item that is generated by a selector.
1429 * <p>
1430 * <img width="640" height="342" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapIterable.f.png" alt="">
1431 * <dl>
1432 * <dt><b>Backpressure:</b></dt>
1433 * <dd>The operator honors backpressure from each downstream rail. The source {@code ParallelFlowable}s is
1434 * expected to honor backpressure as well. If the source {@code ParallelFlowable} violates the rule, the operator will
1435 * signal a {@link MissingBackpressureException}.</dd>
1436 * <dt><b>Scheduler:</b></dt>
1437 * <dd>{@code flatMapIterable} does not operate by default on a particular {@link Scheduler}.</dd>
1438 * </dl>
1439 *
1440 * @param <U>
1441 * the type of item emitted by the resulting {@code Iterable}
1442 * @param mapper
1443 * a function that returns an {@code Iterable} sequence of values for when given an item emitted by the
1444 * source {@code ParallelFlowable}
1445 * @param bufferSize
1446 * the number of elements to prefetch from each upstream rail
1447 * @return the new {@code ParallelFlowable} instance
1448 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
1449 * @see #flatMapStream(Function, int)
1450 * @since 3.0.0
1451 * @throws NullPointerException if {@code mapper} is {@code null}
1452 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
1453 */
1454 @CheckReturnValue
1455 @NonNull
1456 @BackpressureSupport(BackpressureKind.FULL)
1457 @SchedulerSupport(SchedulerSupport.NONE)
1458 public final <@NonNull U> ParallelFlowable<U> flatMapIterable(@NonNull Function<? super T, @NonNull ? extends Iterable<? extends U>> mapper, int bufferSize) {
1459 Objects.requireNonNull(mapper, "mapper is null");
1460 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
1461 return RxJavaPlugins.onAssembly(new ParallelFlatMapIterable<>(this, mapper, bufferSize));
1462 }
1463
1464 // -------------------------------------------------------------------------
1465 // JDK 8 Support
1466 // -------------------------------------------------------------------------
1467
1468 /**
1469 * Maps the source values on each 'rail' to an optional and emits its value if any.
1470 * <p>
1471 * Note that the same mapper function may be called from multiple threads concurrently.
1472 * <dl>
1473 * <dt><b>Backpressure:</b></dt>
1474 * <dd>The operator is a pass-through for backpressure and the behavior
1475 * is determined by the upstream and downstream rail behaviors.</dd>
1476 * <dt><b>Scheduler:</b></dt>
1477 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
1478 * </dl>
1479 * @param <R> the output value type
1480 * @param mapper the mapper function turning Ts into optional of Rs.
1481 * @return the new {@code ParallelFlowable} instance
1482 * @since 3.0.0
1483 * @throws NullPointerException if {@code mapper} is {@code null}
1484 */
1485 @CheckReturnValue
1486 @NonNull
1487 @SchedulerSupport(SchedulerSupport.NONE)
1488 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
1489 public final <@NonNull R> ParallelFlowable<R> mapOptional(@NonNull Function<? super T, @NonNull Optional<? extends R>> mapper) {
1490 Objects.requireNonNull(mapper, "mapper is null");
1491 return RxJavaPlugins.onAssembly(new ParallelMapOptional<>(this, mapper));
1492 }
1493
1494 /**
1495 * Maps the source values on each 'rail' to an optional and emits its value if any and
1496 * handles errors based on the given {@link ParallelFailureHandling} enumeration value.
1497 * <p>
1498 * Note that the same mapper function may be called from multiple threads concurrently.
1499 * <dl>
1500 * <dt><b>Backpressure:</b></dt>
1501 * <dd>The operator is a pass-through for backpressure and the behavior
1502 * is determined by the upstream and downstream rail behaviors.</dd>
1503 * <dt><b>Scheduler:</b></dt>
1504 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
1505 * </dl>
1506 * <p>History: 2.0.8 - experimental
1507 * @param <R> the output value type
1508 * @param mapper the mapper function turning Ts into optional of Rs.
1509 * @param errorHandler the enumeration that defines how to handle errors thrown
1510 * from the mapper function
1511 * @return the new {@code ParallelFlowable} instance
1512 * @since 3.0.0
1513 * @throws NullPointerException if {@code mapper} or {@code errorHandler} is {@code null}
1514 */
1515 @CheckReturnValue
1516 @NonNull
1517 @SchedulerSupport(SchedulerSupport.NONE)
1518 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
1519 public final <@NonNull R> ParallelFlowable<R> mapOptional(@NonNull Function<? super T, @NonNull Optional<? extends R>> mapper, @NonNull ParallelFailureHandling errorHandler) {
1520 Objects.requireNonNull(mapper, "mapper is null");
1521 Objects.requireNonNull(errorHandler, "errorHandler is null");
1522 return RxJavaPlugins.onAssembly(new ParallelMapTryOptional<>(this, mapper, errorHandler));
1523 }
1524
1525 /**
1526 * Maps the source values on each 'rail' to an optional and emits its value if any and
1527 * handles errors based on the returned value by the handler function.
1528 * <p>
1529 * Note that the same mapper function may be called from multiple threads concurrently.
1530 * <dl>
1531 * <dt><b>Backpressure:</b></dt>
1532 * <dd>The operator is a pass-through for backpressure and the behavior
1533 * is determined by the upstream and downstream rail behaviors.</dd>
1534 * <dt><b>Scheduler:</b></dt>
1535 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
1536 * </dl>
1537 * <p>History: 2.0.8 - experimental
1538 * @param <R> the output value type
1539 * @param mapper the mapper function turning Ts into optional of Rs.
1540 * @param errorHandler the function called with the current repeat count and
1541 * failure {@link Throwable} and should return one of the {@link ParallelFailureHandling}
1542 * enumeration values to indicate how to proceed.
1543 * @return the new {@code ParallelFlowable} instance
1544 * @throws NullPointerException if {@code mapper} or {@code errorHandler} is {@code null}
1545 * @since 3.0.0
1546 */
1547 @CheckReturnValue
1548 @NonNull
1549 @SchedulerSupport(SchedulerSupport.NONE)
1550 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
1551 public final <@NonNull R> ParallelFlowable<R> mapOptional(@NonNull Function<? super T, @NonNull Optional<? extends R>> mapper, @NonNull BiFunction<? super Long, ? super Throwable, ParallelFailureHandling> errorHandler) {
1552 Objects.requireNonNull(mapper, "mapper is null");
1553 Objects.requireNonNull(errorHandler, "errorHandler is null");
1554 return RxJavaPlugins.onAssembly(new ParallelMapTryOptional<>(this, mapper, errorHandler));
1555 }
1556
1557 /**
1558 * Maps each upstream item on each rail into a {@link Stream} and emits the {@code Stream}'s items to the downstream in a sequential fashion.
1559 * <p>
1560 * <img width="640" height="328" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapStream.f.png" alt="">
1561 * <p>
1562 * Due to the blocking and sequential nature of Java {@code Stream}s, the streams are mapped and consumed in a sequential fashion
1563 * without interleaving (unlike a more general {@link #flatMap(Function)}). Therefore, {@code flatMapStream} and
1564 * {@code concatMapStream} are identical operators and are provided as aliases.
1565 * <p>
1566 * The operator closes the {@code Stream} upon cancellation and when it terminates. The exceptions raised when
1567 * closing a {@code Stream} are routed to the global error handler ({@link RxJavaPlugins#onError(Throwable)}.
1568 * If a {@code Stream} should not be closed, turn it into an {@link Iterable} and use {@link #flatMapIterable(Function)}:
1569 * <pre><code>
1570 * source.flatMapIterable(v -&gt; createStream(v)::iterator);
1571 * </code></pre>
1572 * <p>
1573 * Note that {@code Stream}s can be consumed only once; any subsequent attempt to consume a {@code Stream}
1574 * will result in an {@link IllegalStateException}.
1575 * <p>
1576 * Primitive streams are not supported and items have to be boxed manually (e.g., via {@link IntStream#boxed()}):
1577 * <pre><code>
1578 * source.flatMapStream(v -&gt; IntStream.rangeClosed(v + 1, v + 10).boxed());
1579 * </code></pre>
1580 * <p>
1581 * {@code Stream} does not support concurrent usage so creating and/or consuming the same instance multiple times
1582 * from multiple threads can lead to undefined behavior.
1583 * <dl>
1584 * <dt><b>Backpressure:</b></dt>
1585 * <dd>The operator honors the downstream backpressure and consumes the inner stream only on demand. The operator
1586 * prefetches {@link Flowable#bufferSize()} items of the upstream (then 75% of it after the 75% received)
1587 * and caches them until they are ready to be mapped into {@code Stream}s
1588 * after the current {@code Stream} has been consumed.</dd>
1589 * <dt><b>Scheduler:</b></dt>
1590 * <dd>{@code flatMapStream} does not operate by default on a particular {@link Scheduler}.</dd>
1591 * </dl>
1592 *
1593 * @param <R> the element type of the {@code Stream}s and the result
1594 * @param mapper the function that receives an upstream item and should return a {@code Stream} whose elements
1595 * will be emitted to the downstream
1596 * @return the new {@code ParallelFlowable} instance
1597 * @throws NullPointerException if {@code mapper} is {@code null}
1598 * @see #flatMap(Function)
1599 * @see #flatMapIterable(Function)
1600 * @see #flatMapStream(Function, int)
1601 * @since 3.0.0
1602 */
1603 @CheckReturnValue
1604 @BackpressureSupport(BackpressureKind.FULL)
1605 @SchedulerSupport(SchedulerSupport.NONE)
1606 @NonNull
1607 public final <@NonNull R> ParallelFlowable<R> flatMapStream(@NonNull Function<? super T, @NonNull ? extends Stream<? extends R>> mapper) {
1608 return flatMapStream(mapper, Flowable.bufferSize());
1609 }
1610
1611 /**
1612 * Maps each upstream item of each rail into a {@link Stream} and emits the {@code Stream}'s items to the downstream in a sequential fashion.
1613 * <p>
1614 * <img width="640" height="270" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapStream.fi.png" alt="">
1615 * <p>
1616 * Due to the blocking and sequential nature of Java {@code Stream}s, the streams are mapped and consumed in a sequential fashion
1617 * without interleaving (unlike a more general {@link #flatMap(Function)}). Therefore, {@code flatMapStream} and
1618 * {@code concatMapStream} are identical operators and are provided as aliases.
1619 * <p>
1620 * The operator closes the {@code Stream} upon cancellation and when it terminates. The exceptions raised when
1621 * closing a {@code Stream} are routed to the global error handler ({@link RxJavaPlugins#onError(Throwable)}.
1622 * If a {@code Stream} should not be closed, turn it into an {@link Iterable} and use {@link #flatMapIterable(Function, int)}:
1623 * <pre><code>
1624 * source.flatMapIterable(v -&gt; createStream(v)::iterator, 32);
1625 * </code></pre>
1626 * <p>
1627 * Note that {@code Stream}s can be consumed only once; any subsequent attempt to consume a {@code Stream}
1628 * will result in an {@link IllegalStateException}.
1629 * <p>
1630 * Primitive streams are not supported and items have to be boxed manually (e.g., via {@link IntStream#boxed()}):
1631 * <pre><code>
1632 * source.flatMapStream(v -&gt; IntStream.rangeClosed(v + 1, v + 10).boxed(), 32);
1633 * </code></pre>
1634 * <p>
1635 * {@code Stream} does not support concurrent usage so creating and/or consuming the same instance multiple times
1636 * from multiple threads can lead to undefined behavior.
1637 * <dl>
1638 * <dt><b>Backpressure:</b></dt>
1639 * <dd>The operator honors the downstream backpressure and consumes the inner stream only on demand. The operator
1640 * prefetches the given amount of upstream items and caches them until they are ready to be mapped into {@code Stream}s
1641 * after the current {@code Stream} has been consumed.</dd>
1642 * <dt><b>Scheduler:</b></dt>
1643 * <dd>{@code flatMapStream} does not operate by default on a particular {@link Scheduler}.</dd>
1644 * </dl>
1645 *
1646 * @param <R> the element type of the {@code Stream}s and the result
1647 * @param mapper the function that receives an upstream item and should return a {@code Stream} whose elements
1648 * will be emitted to the downstream
1649 * @param prefetch the number of upstream items to request upfront, then 75% of this amount after each 75% upstream items received
1650 * @return the new {@code ParallelFlowable} instance
1651 * @throws NullPointerException if {@code mapper} is {@code null}
1652 * @throws IllegalArgumentException if {@code prefetch} is non-positive
1653 * @see #flatMap(Function, boolean, int)
1654 * @see #flatMapIterable(Function, int)
1655 * @since 3.0.0
1656 */
1657 @CheckReturnValue
1658 @BackpressureSupport(BackpressureKind.FULL)
1659 @SchedulerSupport(SchedulerSupport.NONE)
1660 @NonNull
1661 public final <@NonNull R> ParallelFlowable<R> flatMapStream(@NonNull Function<? super T, @NonNull ? extends Stream<? extends R>> mapper, int prefetch) {
1662 Objects.requireNonNull(mapper, "mapper is null");
1663 ObjectHelper.verifyPositive(prefetch, "prefetch");
1664 return RxJavaPlugins.onAssembly(new ParallelFlatMapStream<>(this, mapper, prefetch));
1665 }
1666
1667 /**
1668 * Reduces all values within a 'rail' and across 'rails' with a callbacks
1669 * of the given {@link Collector} into one {@link Flowable} containing a single value.
1670 * <p>
1671 * Each parallel rail receives its own {@link Collector#accumulator()} and
1672 * {@link Collector#combiner()}.
1673 * <dl>
1674 * <dt><b>Backpressure:</b></dt>
1675 * <dd>The operator honors backpressure from the downstream and consumes
1676 * the upstream rails in an unbounded manner (requesting {@link Long#MAX_VALUE}).</dd>
1677 * <dt><b>Scheduler:</b></dt>
1678 * <dd>{@code collect} does not operate by default on a particular {@link Scheduler}.</dd>
1679 * </dl>
1680 * @param <A> the accumulator type
1681 * @param <R> the output value type
1682 * @param collector the {@code Collector} instance
1683 * @return the new {@code Flowable} instance emitting the collected value.
1684 * @throws NullPointerException if {@code collector} is {@code null}
1685 * @since 3.0.0
1686 */
1687 @CheckReturnValue
1688 @NonNull
1689 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
1690 @SchedulerSupport(SchedulerSupport.NONE)
1691 public final <@NonNull A, @NonNull R> Flowable<R> collect(@NonNull Collector<T, A, R> collector) {
1692 Objects.requireNonNull(collector, "collector is null");
1693 return RxJavaPlugins.onAssembly(new ParallelCollector<>(this, collector));
1694 }
1695 }