You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/ISSUE_TEMPLATE.md
+2-2
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,10 @@
1
1
Thanks for using RxJava but before you post an issue, please consider the following points:
2
2
3
-
-[ ] Please include the library version number, including the minor and patch version, in the issue text. In addition, if you'd include the major version in the title (such as `2.x`) that would be great.
3
+
-[ ] Please include the library version number, including the minor and patch version, in the issue text. In addition, if you'd include the major version in the title (such as `3.x`) that would be great.
4
4
5
5
-[ ] If you think you found a bug, please include a code sample that reproduces the problem. Dumping a stacktrace is usually not enough for us.
6
6
7
-
-[ ] RxJava has more than 150 operators, we recommend searching the [javadoc](http://reactivex.io/RxJava/2.x/javadoc/io/reactivex/Observable.html) for keywords of what you try to accomplish.
7
+
-[ ] RxJava has more than 150 operators, we recommend searching the [javadoc](http://reactivex.io/RxJava/3.x/javadoc/io/reactivex/Observable.html) for keywords of what you try to accomplish.
8
8
9
9
-[ ] If you have a question/issue about a library/technology built on top of RxJava (such as Retrofit, RxNetty, etc.), please consider asking a question on StackOverflow first (then maybe on their issue list).
Copy file name to clipboardExpand all lines: DESIGN.md
+11-11
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
-
## RxJava v2 Design
1
+
## RxJava v3 Design
2
2
3
-
This document explains the terminology, principles, contracts, and other aspects of the design of RxJava v2.
3
+
This document explains the terminology, principles, contracts, and other aspects of the design of RxJava v3.
4
4
Its intended audience is the implementers of the library.
5
5
6
6
### Terminology & Definitions
@@ -41,7 +41,7 @@ Examples:
41
41
-`Observable` (RxJS, Rx.Net, RxJava v1.x without backpressure, RxJava v2).
42
42
- Callbacks (the producer calls the function at its convenience).
43
43
- IRQ, mouse events, IO interrupts.
44
-
-2.x `Flowable` (with `request(n)` credit always granted faster or in larger quantity than producer).
44
+
-3.x `Flowable` (with `request(n)` credit always granted faster or in larger quantity than producer).
45
45
- Reactive Streams `Publisher` (with `request(n)` credit always granted faster or in larger quantity than producer).
46
46
- Java 9 `Flow.Publisher` (with `request(n)` credit always granted faster than or in larger quantity than producer).
47
47
@@ -53,8 +53,8 @@ Consumer is in charge. Producer has to do whatever it needs to keep up.
53
53
Examples:
54
54
55
55
-`Iterable`.
56
-
-2.x/1.x `Observable` (without concurrency, producer and consumer on the same thread).
57
-
-2.x `Flowable` (without concurrency, producer and consumer on the same thread).
56
+
-3.x/1.x `Observable` (without concurrency, producer and consumer on the same thread).
57
+
-3.x `Flowable` (without concurrency, producer and consumer on the same thread).
58
58
- Reactive Streams `Publisher` (without concurrency, producer and consumer on the same thread).
59
59
- Java 9 `Flow.Publisher` (without concurrency, producer and consumer on the same thread).
60
60
@@ -67,13 +67,13 @@ Examples:
67
67
68
68
-`Future` & `Promise`.
69
69
-`Single` (lazy `Future`).
70
-
-2.x `Flowable`.
70
+
-3.x `Flowable`.
71
71
- Reactive Streams `Publisher`.
72
72
- Java 9 `Flow.Publisher`.
73
73
- 1.x `Observable` (with backpressure).
74
74
-`AsyncEnumerable`/`AsyncIterable`.
75
75
76
-
There is an overhead (performance and mental) for achieving this, which is why we also have the 2.x `Observable` without backpressure.
76
+
There is an overhead (performance and mental) for achieving this, which is why we also have the 3.x `Observable` without backpressure.
77
77
78
78
79
79
##### Flow Control
@@ -325,7 +325,7 @@ In the addition of the previous rules, an operator for `Flowable`:
325
325
326
326
### Creation
327
327
328
-
Unlike RxJava 1.x, 2.x base classes are to be abstract, stateless and generally no longer wrap an `onSubscribe` callback - this saves allocation in assembly time without limiting the expressiveness. Operator methods and standard factories still live as final on the base classes.
328
+
Unlike RxJava 1.x, 3.x base classes are to be abstract, stateless and generally no longer wrap an `onSubscribe` callback - this saves allocation in assembly time without limiting the expressiveness. Operator methods and standard factories still live as final on the base classes.
329
329
330
330
Instead of the indirection of an `onSubscribe` and `lift`, operators are to be implemented by extending the base classes. For example, the `map`
331
331
operator will look like this:
@@ -489,11 +489,11 @@ The final `subscribe` will *not* invoke `cancel`/`dispose` after receiving an `o
489
489
490
490
### JVM target and source compatibility
491
491
492
-
The 2.x version will target JDK6+ to let Android users consume the new version of RxJava.
492
+
The 3.x version will target JDK6+ to let Android users consume the new version of RxJava.
493
493
494
494
### Future work
495
495
496
-
This section contains current design work which needs more discussion and elaboration before it is merged into this document as a stated goal for 2.x.
496
+
This section contains current design work which needs more discussion and elaboration before it is merged into this document as a stated goal for 3.x.
497
497
498
498
#### Custom Observable, Single, Completable, or Flowable
For performance, the mode is an integer bitflags setup, called early during subscription time, and allows negotiating the fusion mode. Usually, producers can do only one mode and consumers can do both mode. Because fused, intermediate operators attach logic (which is many times user-callback) to the exit point of the queue interface (poll()), it may change the computation location of those callbacks in an unwanted way. The flag `BOUNDARY` is added by consumers indicating that they will consume the queue over an async boundary. Intermediate operators, such as `map` and `filter` then can reject the fusion in such sequences.
588
588
589
-
Since RxJava 2.x is still JDK 6 compatible, the `QueueSubscription` can't itself default unnecessary methods and implementations are required to throw `UnsupportedOperationException` for `Queue` methods other than the following:
589
+
Since RxJava 3.x is still JDK 6 compatible, the `QueueSubscription` can't itself default unnecessary methods and implementations are required to throw `UnsupportedOperationException` for `Queue` methods other than the following:
RxJava is a Java VM implementation of [Reactive Extensions](http://reactivex.io): a library for composing asynchronous and event-based programs by using observable sequences.
8
8
9
9
It extends the [observer pattern](http://en.wikipedia.org/wiki/Observer_pattern) to support sequences of data/events and adds operators that allow you to compose sequences together declaratively while abstracting away concerns about things like low-level threading, synchronization, thread-safety and concurrent data structures.
10
10
11
-
#### Version 2.x ([Javadoc](http://reactivex.io/RxJava/2.x/javadoc/))
11
+
#### Version 3.x ([Javadoc](http://reactivex.io/RxJava/3.x/javadoc/))
12
12
13
13
- single dependency: [Reactive-Streams](https://github.com/reactive-streams/reactive-streams-jvm)
14
14
- continued support for Java 6+ & [Android](https://github.com/ReactiveX/RxAndroid) 2.3+
15
-
- performance gains through design changes learned through the 1.x cycle and through [Reactive-Streams-Commons](https://github.com/reactor/reactive-streams-commons) research project.
15
+
- fixed API mistakes and many limits of RxJava 2
16
+
- intended to be a replacement for RxJava 2 with relatively few binary incompatible changes
16
17
- Java 8 lambda-friendly API
17
-
- non-opinionated about source of concurrency (threads, pools, event loops, fibers, actors, etc)
18
+
- non-opinionated about source of concurrency (threads, pools, event loops, fibers, actors, etc.)
18
19
- async or synchronous execution
19
20
- virtual time and schedulers for parameterized concurrency
21
+
- test and diagnostic support via test schedulers, test consumers and plugin hooks
20
22
21
-
Version 2.x and 1.x will live side-by-side for several years. They will have different group ids (`io.reactivex.rxjava2` vs `io.reactivex`) and namespaces (`io.reactivex` vs `rx`).
23
+
Learn more about RxJava in general on the <ahref="https://github.com/ReactiveX/RxJava/wiki">Wiki Home</a>.
22
24
23
-
See the differences between version 1.x and 2.x in the wiki article [What's different in 2.0](https://github.com/ReactiveX/RxJava/wiki/What's-different-in-2.0). Learn more about RxJava in general on the <ahref="https://github.com/ReactiveX/RxJava/wiki">Wiki Home</a>.
25
+
#### Version 2.x
26
+
27
+
The [2.x version](https://github.com/ReactiveX/RxJava/tree/2.x) will be supported with bugfixes and important documentation updates till
28
+
**December 31, 2020**. No new features will be added to 2.x.
24
29
25
30
#### Version 1.x
26
31
@@ -30,13 +35,13 @@ The [1.x version](https://github.com/ReactiveX/RxJava/tree/1.x) is end-of-life a
30
35
31
36
### Setting up the dependency
32
37
33
-
The first step is to include RxJava 2 into your project, for example, as a Gradle compile dependency:
38
+
The first step is to include RxJava 3 into your project, for example, as a Gradle compile dependency:
(Please replace `x` and `y` with the latest version numbers: [](https://maven-badges.herokuapp.com/maven-central/io.reactivex.rxjava2/rxjava)
44
+
(Please replace `x` and `y` with the latest version numbers: [](https://maven-badges.herokuapp.com/maven-central/io.reactivex.rxjava3/rxjava)
40
45
)
41
46
42
47
### Hello World
@@ -70,13 +75,13 @@ Flowable.just("Hello world")
70
75
71
76
### Base classes
72
77
73
-
RxJava 2 features several base classes you can discover operators on:
78
+
RxJava 3 features several base classes you can discover operators on:
74
79
75
-
-[`io.reactivex.Flowable`](http://reactivex.io/RxJava/2.x/javadoc/io/reactivex/Flowable.html): 0..N flows, supporting Reactive-Streams and backpressure
76
-
-[`io.reactivex.Observable`](http://reactivex.io/RxJava/2.x/javadoc/io/reactivex/Observable.html): 0..N flows, no backpressure,
77
-
-[`io.reactivex.Single`](http://reactivex.io/RxJava/2.x/javadoc/io/reactivex/Single.html): a flow of exactly 1 item or an error,
78
-
-[`io.reactivex.Completable`](http://reactivex.io/RxJava/2.x/javadoc/io/reactivex/Completable.html): a flow without items but only a completion or error signal,
79
-
-[`io.reactivex.Maybe`](http://reactivex.io/RxJava/2.x/javadoc/io/reactivex/Maybe.html): a flow with no items, exactly one item or an error.
80
+
-[`io.reactivex.Flowable`](http://reactivex.io/RxJava/3.x/javadoc/io/reactivex/Flowable.html): 0..N flows, supporting Reactive-Streams and backpressure
81
+
-[`io.reactivex.Observable`](http://reactivex.io/RxJava/3.x/javadoc/io/reactivex/Observable.html): 0..N flows, no backpressure,
82
+
-[`io.reactivex.Single`](http://reactivex.io/RxJava/3.x/javadoc/io/reactivex/Single.html): a flow of exactly 1 item or an error,
83
+
-[`io.reactivex.Completable`](http://reactivex.io/RxJava/3.x/javadoc/io/reactivex/Completable.html): a flow without items but only a completion or error signal,
84
+
-[`io.reactivex.Maybe`](http://reactivex.io/RxJava/3.x/javadoc/io/reactivex/Maybe.html): a flow with no items, exactly one item or an error.
80
85
81
86
### Some terminology
82
87
@@ -193,7 +198,7 @@ Typically, you can move computations or blocking IO to some other thread via `su
193
198
194
199
### Schedulers
195
200
196
-
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 2 features several standard schedulers accessible via `Schedulers` utility class.
201
+
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.
197
202
198
203
-`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`.
199
204
-`Schedulers.io()`: Run I/O-like or blocking operations on a dynamically changing set of threads.
The base classes can be considered heavy due to the sheer number of static and instance methods on them. RxJava 2's design was heavily influenced by the [Reactive Streams](https://github.com/reactive-streams/reactive-streams-jvm#reactive-streams) specification, therefore, the library features a class and an interface per each reactive type:
476
+
The base classes can be considered heavy due to the sheer number of static and instance methods on them. RxJava 3's design was heavily influenced by the [Reactive Streams](https://github.com/reactive-streams/reactive-streams-jvm#reactive-streams) specification, therefore, the library features a class and an interface per each reactive type:
472
477
473
478
| Type | Class | Interface | Consumer |
474
479
|------|-------|-----------|----------|
@@ -496,11 +501,11 @@ For further details, consult the [wiki](https://github.com/ReactiveX/RxJava/wiki
496
501
497
502
## Versioning
498
503
499
-
Version 2.x is now considered stable and final. Version 1.x will be supported for several years along with 2.x. Enhancements and bugfixes will be synchronized between the two in a timely manner.
504
+
Version 3.x is in development. Bugfixes will be applied to both 2.xand 3.x branches, but new features will only be added to 3.x.
500
505
501
-
Minor 2.x increments (such as 2.1, 2.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.
506
+
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.
502
507
503
-
Patch 2.x.y increments (such as 2.0.0 -> 2.0.1, 2.3.1 -> 2.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.
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.
504
509
505
510
#### @Beta
506
511
@@ -521,44 +526,44 @@ All code inside the `io.reactivex.internal.*` packages is considered private API
- Javadoc of a specific [release version](https://github.com/ReactiveX/RxJava/tags): `http://reactivex.io/RxJava/3.x/javadoc/3.x.y/`
527
532
528
533
## Binaries
529
534
530
-
Binaries and dependency information for Maven, Ivy, Gradle and others can be found at [http://search.maven.org](http://search.maven.org/#search%7Cga%7C1%7Cio.reactivex.rxjava2).
535
+
Binaries and dependency information for Maven, Ivy, Gradle and others can be found at [http://search.maven.org](http://search.maven.org/#search%7Cga%7C1%7Cio.reactivex.rxjava3).
0 commit comments