Skip to content

Commit 5f283f0

Browse files
authored
Cherry-pick fixes from #6683 (#6699)
1 parent 8ed6cc1 commit 5f283f0

File tree

1 file changed

+34
-14
lines changed

1 file changed

+34
-14
lines changed

README.md

Lines changed: 34 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ It extends the [observer pattern](http://en.wikipedia.org/wiki/Observer_pattern)
1515
- fixed API mistakes and many limits of RxJava 2
1616
- intended to be a replacement for RxJava 2 with relatively few binary incompatible changes
1717
- Java 8 lambda-friendly API
18-
- non-opinionated about source of concurrency (threads, pools, event loops, fibers, actors, etc.)
18+
- non-opinionated about the source of concurrency (threads, pools, event loops, fibers, actors, etc.)
1919
- async or synchronous execution
2020
- virtual time and schedulers for parameterized concurrency
2121
- test and diagnostic support via test schedulers, test consumers and plugin hooks
@@ -24,7 +24,7 @@ Learn more about RxJava in general on the <a href="https://github.com/ReactiveX/
2424

2525
#### Version 2.x
2626

27-
The [2.x version](https://github.com/ReactiveX/RxJava/tree/2.x) will be supported with bugfixes and important documentation updates till
27+
The [2.x version](https://github.com/ReactiveX/RxJava/tree/2.x) will be supported with bugfixes and important documentation updates until
2828
**December 31, 2020**. No new features will be added to 2.x.
2929

3030
#### Version 1.x
@@ -97,7 +97,7 @@ source.operator1().operator2().operator3().subscribe(consumer);
9797
source.flatMap(value -> source.operator1().operator2().operator3());
9898
```
9999

100-
Here, if we imagine ourselves on `operator2`, looking to the left towards the source, is called the **upstream**. Looking to the right towards the subscriber/consumer, is called the **downstream**. This is often more apparent when each element is written on a separate line:
100+
Here, if we imagine ourselves on `operator2`, looking to the left towards the source is called the **upstream**. Looking to the right towards the subscriber/consumer is called the **downstream**. This is often more apparent when each element is written on a separate line:
101101

102102
```java
103103
source
@@ -113,9 +113,9 @@ In RxJava's documentation, **emission**, **emits**, **item**, **event**, **signa
113113

114114
#### Backpressure
115115

116-
When the dataflow runs through asynchronous steps, each step may perform different things with different speed. To avoid overwhelming such steps, which usually would manifest itself as increased memory usage due to temporary buffering or the need for skipping/dropping data, a so-called backpressure is applied, which is a form of flow control where the steps can express how many items are they ready to process. This allows constraining the memory usage of the dataflows in situations where there is generally no way for a step to know how many items the upstream will send to it.
116+
When the dataflow runs through asynchronous steps, each step may perform different things with different speed. To avoid overwhelming such steps, which usually would manifest itself as increased memory usage due to temporary buffering or the need for skipping/dropping data, so-called backpressure is applied, which is a form of flow control where the steps can express how many items are they ready to process. This allows constraining the memory usage of the dataflows in situations where there is generally no way for a step to know how many items the upstream will send to it.
117117

118-
In RxJava, the dedicated `Flowable` class is designated to support backpressure and `Observable` is dedicated for the non-backpressured operations (short sequences, GUI interactions, etc.). The other types, `Single`, `Maybe` and `Completable` don't support backpressure nor should they; there is always room to store one item temporarily.
118+
In RxJava, the dedicated `Flowable` class is designated to support backpressure and `Observable` is dedicated to the non-backpressured operations (short sequences, GUI interactions, etc.). The other types, `Single`, `Maybe` and `Completable` don't support backpressure nor should they; there is always room to store one item temporarily.
119119

120120
#### Assembly time
121121

@@ -200,16 +200,16 @@ Typically, you can move computations or blocking IO to some other thread via `su
200200

201201
### Schedulers
202202

203-
RxJava operators don't work with `Thread`s or `ExecutorService`s directly but with so called `Scheduler`s that abstract away sources of concurrency behind a uniform API. RxJava 3 features several standard schedulers accessible via `Schedulers` utility class.
203+
RxJava operators don't work with `Thread`s or `ExecutorService`s directly but with so-called `Scheduler`s that abstract away sources of concurrency behind a uniform API. RxJava 3 features several standard schedulers accessible via `Schedulers` utility class.
204204

205-
- `Schedulers.computation()`: Run computation intensive work on a fixed number of dedicated threads in the background. Most asynchronous operator use this as their default `Scheduler`.
205+
- `Schedulers.computation()`: Run computation intensive work on a fixed number of dedicated threads in the background. Most asynchronous operators use this as their default `Scheduler`.
206206
- `Schedulers.io()`: Run I/O-like or blocking operations on a dynamically changing set of threads.
207207
- `Schedulers.single()`: Run work on a single thread in a sequential and FIFO manner.
208208
- `Schedulers.trampoline()`: Run work in a sequential and FIFO manner in one of the participating threads, usually for testing purposes.
209209

210210
These are available on all JVM platforms but some specific platforms, such as Android, have their own typical `Scheduler`s defined: `AndroidSchedulers.mainThread()`, `SwingScheduler.instance()` or `JavaFXSchedulers.gui()`.
211211

212-
In addition, there is option to wrap an existing `Executor` (and its subtypes such as `ExecutorService`) into a `Scheduler` via `Schedulers.from(Executor)`. This can be used, for example, to have a larger but still fixed pool of threads (unlike `computation()` and `io()` respectively).
212+
In addition, there is an option to wrap an existing `Executor` (and its subtypes such as `ExecutorService`) into a `Scheduler` via `Schedulers.from(Executor)`. This can be used, for example, to have a larger but still fixed pool of threads (unlike `computation()` and `io()` respectively).
213213

214214
The `Thread.sleep(2000);` at the end is no accident. In RxJava the default `Scheduler`s run on daemon threads, which means once the Java main thread exits, they all get stopped and background computations may never happen. Sleeping for some time in this example situations lets you see the output of the flow on the console with time to spare.
215215

@@ -242,7 +242,7 @@ Flowable.range(1, 10)
242242

243243
Practically, parallelism in RxJava means running independent flows and merging their results back into a single flow. The operator `flatMap` does this by first mapping each number from 1 to 10 into its own individual `Flowable`, runs them and merges the computed squares.
244244

245-
Note, however, that `flatMap` doesn't guarantee any order and the end result from the inner flows may end up interleaved. There are alternative operators:
245+
Note, however, that `flatMap` doesn't guarantee any order and the items from the inner flows may end up interleaved. There are alternative operators:
246246

247247
- `concatMap` that maps and runs one inner flow at a time and
248248
- `concatMapEager` which runs all inner flows "at once" but the output flow will be in the order those inner flows were created.
@@ -362,7 +362,7 @@ Observable.range(1, 10)
362362

363363
### Type conversions
364364

365-
Sometimes, a source or service returns a different type than the flow that is supposed to work with it. For example, in the inventory example above, `getDemandAsync` could return a `Single<DemandRecord>`. If the code example is left unchanged, this will result in a compile time error (however, often with misleading error message about lack of overload).
365+
Sometimes, a source or service returns a different type than the flow that is supposed to work with it. For example, in the inventory example above, `getDemandAsync` could return a `Single<DemandRecord>`. If the code example is left unchanged, this will result in a compile-time error (however, often with a misleading error message about lack of overload).
366366

367367
In such situations, there are usually two options to fix the transformation: 1) convert to the desired type or 2) find and use an overload of the specific operator supporting the different type.
368368

@@ -378,7 +378,7 @@ Each reactive base class features operators that can perform such conversions, i
378378
|**Maybe** | `toFlowable`<sup>3</sup> | `toObservable` | `toSingle` | | `ignoreElement` |
379379
|**Completable** | `toFlowable` | `toObservable` | `toSingle` | `toMaybe` | |
380380

381-
<sup>1</sup>: When turning a multi-valued source into a single valued source, one should decide which of the many source values should be considered as the result.
381+
<sup>1</sup>: When turning a multi-valued source into a single-valued source, one should decide which of the many source values should be considered as the result.
382382

383383
<sup>2</sup>: Turning an `Observable` into `Flowable` requires an additional decision: what to do with the potential unconstrained flow
384384
of the source `Observable`? There are several strategies available (such as buffering, dropping, keeping the latest) via the `BackpressureStrategy` parameter or via standard `Flowable` operators such as `onBackpressureBuffer`, `onBackpressureDrop`, `onBackpressureLatest` which also
@@ -487,6 +487,26 @@ The base classes can be considered heavy due to the sheer number of static and i
487487

488488
<sup>2</sup>The naming convention of the interface was to append `Source` to the semi-traditional class name. There is no `FlowableSource` since `Publisher` is provided by the Reactive Streams library (and subtyping it wouldn't have helped with interoperation either). These interfaces are, however, not standard in the sense of the Reactive Streams specification and are currently RxJava specific only.
489489

490+
### R8 and ProGuard settings
491+
492+
By default, RxJava doesn't require any ProGuard/R8 settings and should work without problems. Unfortunately, the Reactive Streams dependency since version 1.0.3 has embedded Java 9 class files in its JAR that can cause warnings with ProGuard:
493+
494+
```
495+
Warning: org.reactivestreams.FlowAdapters$FlowPublisherFromReactive: can't find superclass or interface java.util.concurrent.Flow$Publisher
496+
Warning: org.reactivestreams.FlowAdapters$FlowToReactiveProcessor: can't find superclass or interface java.util.concurrent.Flow$Processor
497+
Warning: org.reactivestreams.FlowAdapters$FlowToReactiveSubscriber: can't find superclass or interface java.util.concurrent.Flow$Subscriber
498+
Warning: org.reactivestreams.FlowAdapters$FlowToReactiveSubscription: can't find superclass or interface java.util.concurrent.Flow$Subscription
499+
Warning: org.reactivestreams.FlowAdapters: can't find referenced class java.util.concurrent.Flow$Publisher
500+
```
501+
502+
It is recommended one sets up one or more of the following `-dontwarn` entries:
503+
504+
```
505+
-dontwarn org.reactivestreams.FlowAdapters
506+
-dontwarn org.reactivestreams.**
507+
-dontwarn java.util.concurrent.flow.**
508+
-dontwarn java.util.concurrent.**```
509+
490510
### Further reading
491511
492512
For further details, consult the [wiki](https://github.com/ReactiveX/RxJava/wiki).
@@ -505,11 +525,11 @@ Version 3.x is in development. Bugfixes will be applied to both 2.x and 3.x bran
505525
506526
Minor 3.x increments (such as 3.1, 3.2, etc) will occur when non-trivial new functionality is added or significant enhancements or bug fixes occur that may have behavioral changes that may affect some edge cases (such as dependence on behavior resulting from a bug). An example of an enhancement that would classify as this is adding reactive pull backpressure support to an operator that previously did not support it. This should be backwards compatible but does behave differently.
507527
508-
Patch 3.x.y increments (such as 3.0.0 -> 3.0.1, 3.3.1 -> 3.3.2, etc) will occur for bug fixes and trivial functionality (like adding a method overload). New functionality marked with an [`@Beta`][beta source link] or [`@Experimental`][experimental source link] annotation can also be added in patch releases to allow rapid exploration and iteration of unstable new functionality.
528+
Patch 3.x.y increments (such as 3.0.0 -> 3.0.1, 3.3.1 -> 3.3.2, etc) will occur for bug fixes and trivial functionality (like adding a method overload). New functionality marked with an [`@Beta`][beta source link] or [`@Experimental`][experimental source link] annotation can also be added in the patch releases to allow rapid exploration and iteration of unstable new functionality.
509529
510530
#### @Beta
511531
512-
APIs marked with the [`@Beta`][beta source link] annotation at the class or method level are subject to change. They can be modified in any way, or even removed, at any time. If your code is a library itself (i.e. it is used on the CLASSPATH of users outside your own control), you should not use beta APIs, unless you repackage them (e.g. using ProGuard, shading, etc).
532+
APIs marked with the [`@Beta`][beta source link] annotation at the class or method level are subject to change. They can be modified in any way, or even removed, at any time. If your code is a library itself (i.e. it is used on the CLASSPATH of users outside your control), you should not use beta APIs, unless you repackage them (e.g. using ProGuard, shading, etc).
513533
514534
#### @Experimental
515535
@@ -521,7 +541,7 @@ APIs marked with the `@Deprecated` annotation at the class or method level will
521541
522542
#### io.reactivex.rxjava3.internal.*
523543
524-
All code inside the `io.reactivex.rxjava3.internal.*` packages is considered private API and should not be relied upon at all. It can change at any time.
544+
All code inside the `io.reactivex.rxjava3.internal.*` packages are considered private API and should not be relied upon at all. It can change at any time.
525545
526546
## Full Documentation
527547

0 commit comments

Comments
 (0)