|
1 | 1 | # Reactive Streams |
2 | 2 |
|
3 | | -Reactive Streams is an initiative to provide a standard for asynchronous stream processing with non-blocking back pressure on the JVM. |
| 3 | +Reactive Streams is an initiative to provide a standard for asynchronous stream processing with non-blocking back pressure. This encompasses efforts aimed at runtime environments (JVM and JavaScript) as well as network protocols. |
4 | 4 |
|
5 | 5 | ## The Problem |
6 | 6 |
|
7 | | -Handling streams of data—especially “live” data whose volume is not predetermined—requires special care in an asynchronous system. The most prominent issue is that resource consumption needs to be carefully controlled such that a fast data source does not overwhelm the stream destination. Asynchrony is needed in order to enable the parallel use of computing resources, on collaborating network hosts or multiple CPU cores within a single machine. |
| 7 | +Handling streams of data—especially “live” data whose volume is not predetermined—requires special care in an asynchronous system. The most prominent issue is that resource consumption needs to be controlled such that a fast data source does not overwhelm the stream destination. Asynchrony is needed in order to enable the parallel use of computing resources, on collaborating network hosts or multiple CPU cores within a single machine. |
8 | 8 |
|
9 | | -The main goal of Reactive Streams is to govern the exchange of stream data across an asynchronous boundary—think passing elements on to another thread or thread-pool—while ensuring that the receiving side is not forced to buffer arbitrary amounts of data. In other words, back pressure is an integral part of this model in order to allow the queues which mediate between threads to be bounded. The benefits of asynchronous processing would be negated if the communication of back pressure were synchronous (see also the [Reactive Manifesto](http://reactivemanifesto.org/)), therefore care has been taken to mandate fully non-blocking and asynchronous behavior of all aspects of a Reactive Streams implementation. |
| 9 | +The main goal of Reactive Streams is to govern the exchange of stream data across an asynchronous boundary—think passing elements on to another thread or thread-pool—while ensuring that the receiving side is not forced to buffer arbitrary amounts of data. In other words, back pressure is an integral part of this model in order to allow the queues which mediate between threads to be bounded. The benefits of asynchronous processing would be negated if the communication of back pressure were synchronous (see also the [Reactive Manifesto](http://reactivemanifesto.org/)), therefore care has to be taken to mandate fully non-blocking and asynchronous behavior of all aspects of a Reactive Streams implementation. |
10 | 10 |
|
11 | 11 | It is the intention of this specification to allow the creation of many conforming implementations, which by virtue of abiding by the rules will be able to interoperate smoothly, preserving the aforementioned benefits and characteristics across the whole processing graph of a stream application. |
12 | 12 |
|
13 | 13 | ## Scope |
14 | 14 |
|
15 | | -The scope of Reactive Streams is to find a minimal set of interfaces and methods that will describe the necessary operations and entities to achieve the goal—asynchronous streams of data with non-blocking back pressure. |
| 15 | +The scope of Reactive Streams is to find a minimal set of interfaces, methods and protocols that will describe the necessary operations and entities to achieve the goal—asynchronous streams of data with non-blocking back pressure. |
16 | 16 |
|
17 | | -End-user DSLs to create instances of the API interfaces have purposefully been left out of the scope to encourage and enable different implementations that potentially use different programming languages to stay as true as possible to the idioms of that platform. |
| 17 | +End-user DSLs or protocol binding APIs have purposefully been left out of the scope to encourage and enable different implementations that potentially use different programming languages to stay as true as possible to the idioms of their platform. |
18 | 18 |
|
19 | | -We anticipate that acceptance of this Reactive Streams specification and experience with its implementations will together lead to standardized Java platform support in future JDK releases. |
| 19 | +We anticipate that acceptance of this Reactive Streams specification and experience with its implementations will together lead to wide integration, for example including Java platform support in future JDK releases or network protocol support in future web browsers. |
20 | 20 |
|
21 | | -## First Draft Specification |
| 21 | +### Working Groups |
22 | 22 |
|
23 | | -Available immediately is a First Draft Specification covering: |
| 23 | +#### Basic Semantics |
24 | 24 |
|
25 | | -* [Semantics](https://github.com/reactive-streams/reactive-streams/blob/v1.0.0.RC3/README.md#specification)—a specification document |
26 | | -* [API](https://github.com/reactive-streams/reactive-streams/tree/v1.0.0.RC3/api/src/main/java/org/reactivestreams)—Java interfaces for implementations ([javadoc](https://github.com/reactive-streams/reactive-streams.github.io/tree/master/reactive-streams-1.0.0.RC3-javadoc)) |
27 | | -* [TCK](https://github.com/reactive-streams/reactive-streams/tree/v1.0.0.RC3/tck)—a test harness to validate implementations and guide implementor ([javadoc](https://github.com/reactive-streams/reactive-streams.github.io/tree/master/reactive-streams-tck-1.0.0.RC3-javadoc)) |
| 25 | +The basic semantics define how the transmission of stream elements is regulated through back-pressure. How elements are transmitted, their representation during transfer, or how back-pressure is signaled is not part of this specification. |
28 | 26 |
|
29 | | -All of the parts of the Draft Proposal is released under [Creative Commons Zero](http://creativecommons.org/publicdomain/zero/1.0) (Public Domain). |
| 27 | +#### JVM Interfaces |
30 | 28 |
|
31 | | -## Users |
| 29 | +This working group applies the basic semantics to a set of programming interfaces whose main purpose is to allow the interoperation of different conforming implementations and language bindings for passing streams between objects and threads within the JVM, using the shared memory heap. |
32 | 30 |
|
33 | | -Don’t hesitate to take a look at or try out some of the early implementations of the draft spec! |
| 31 | +This work is performed in the [reactive-streams-jvm](https://github.com/reactive-streams/reactive-streams-jvm/) repository. |
34 | 32 |
|
35 | | -For feedback on |
| 33 | +#### JavaScript Interfaces |
36 | 34 |
|
37 | | -* the draft spec, the Reactive Streams initiative or general feedback: |
| 35 | +This working group defines a minimal set of object properties for observing a stream of elements within a JavaScript runtime environment. The goal is to provide a testable specification that allows different implementations to interoperate within that same runtime environment. |
38 | 36 |
|
39 | | - please open an Issue on the [Reactive Streams project](https://github.com/reactive-streams/reactive-streams/issues). |
| 37 | +This work is performed in the [reactive-streams-js](https://github.com/reactive-streams/reactive-streams-js/) repository. |
40 | 38 |
|
41 | | -* the implementations themselves: |
| 39 | +#### Network Protocols |
42 | 40 |
|
43 | | - please direct that to the implementor via their preferred feedback system listed below. |
| 41 | +This working group defines network protocols for passing reactive streams over various transport media that involve serialization and deserialization of the data elements. Examples of such transports are TCP, UDP, HTTP and WebSockets. |
44 | 42 |
|
45 | | -### Implementations of the draft spec |
| 43 | +This work is performed in the [reactive-streams-io](https://github.com/reactive-streams/reactive-streams-io/) repository. |
46 | 44 |
|
47 | | -* Akka Streams |
48 | | - * See this [Activator template](http://www.typesafe.com/activator/template/akka-stream-scala) introducing the [Akka Project](http://akka.io/) implementation in Scala; a Java version will follow shortly. |
| 45 | +## Current State |
| 46 | + |
| 47 | +As of Feb 16, 2015 we have released version 1.0.0-RC3 of Reactive Streams for the JVM, including Java [API](http://www.reactive-streams.org/reactive-streams-1.0.0.RC3-javadoc), a textual [Specification](https://github.com/reactive-streams/reactive-streams-jvm/blob/v1.0.0.RC3/README.md#specification) and a [TCK](http://www.reactive-streams.org/reactive-streams-tck-1.0.0.RC3-javadoc). Corresponding code artifacts are available on Maven Central: |
| 48 | + |
| 49 | + <dependency> |
| 50 | + <groupId>org.reactivestreams</groupId> |
| 51 | + <artifactId>reactive-streams</artifactId> |
| 52 | + <version>1.0.0.RC3</version> |
| 53 | + </dependency> |
| 54 | + <dependency> |
| 55 | + <groupId>org.reactivestreams</groupId> |
| 56 | + <artifactId>reactive-streams-tck</artifactId> |
| 57 | + <version>1.0.0.RC3</version> |
| 58 | + </dependency> |
| 59 | + |
| 60 | +The source code for these is available on [github](https://github.com/reactive-streams/reactive-streams-jvm/tree/v1.0.0.RC3). Please use github issues for providing feedback. |
| 61 | + |
| 62 | +All artifacts and specifications are released under [Creative Commons Zero](http://creativecommons.org/publicdomain/zero/1.0) into the Public Domain. |
| 63 | + |
| 64 | +### Implementations (sorted alphabetically) |
| 65 | + |
| 66 | +#### On the JVM |
| 67 | + |
| 68 | +* [Akka](http://akka.io/) Streams |
| 69 | + * See this [Activator template](http://www.typesafe.com/activator/template/akka-stream-scala) and the [documentation](http://doc.akka.io/docs/akka-stream-and-http-experimental/1.0-M4/index.html). |
49 | 70 | * Please give [Feedback](http://doc.akka.io/docs/akka/current/project/issue-tracking.html) on the issue tracker. |
50 | | -* Reactor Composable |
51 | | - * [Reactor (1.1+)](http://github.com/reactor/reactor) |
52 | | - * Current Implementation Draft is being explored for 1.1 and onwards, see Reactor Composable |
53 | | -* RxJava |
54 | | - * See [github.com/ReactiveX/RxJavaReactiveStreams](https://github.com/ReactiveX/RxJavaReactiveStreams). |
55 | 71 | * [Ratpack](http://www.ratpack.io) |
56 | 72 | * See the [“Streams”](http://www.ratpack.io/manual/current/streams.html) chapter of the manual. |
| 73 | +* [Reactor](http://projectreactor.io/) |
| 74 | + * For the documentation see [here](http://projectreactor.io/docs/reference/streams.html). |
| 75 | +* [RxJava](http://reactivex.io/) |
| 76 | + * See [github.com/ReactiveX/RxJavaReactiveStreams](https://github.com/ReactiveX/RxJavaReactiveStreams). |
| 77 | +* [Vert.x 3.0](http://vertx.io) |
| 78 | + * Vert.x 3.0 is currently in alpha. The reactive streams implementation can be found [here](https://github.com/vert-x3/ext/tree/master/ext-reactive-streams). |
57 | 79 |
|
58 | | -## Implementors |
| 80 | +##### A Note for Implementors |
59 | 81 |
|
60 | | -To get started implementing the draft specification, it is recommended to start by reading the [README](https://github.com/reactive-streams/reactive-streams/blob/v1.0.0.RC3/README.md), then taking a look at the [Specification](https://github.com/reactive-streams/reactive-streams/blob/v1.0.0.RC3/README.md#specification) then taking a look at the [TCK](https://github.com/reactive-streams/reactive-streams/tree/v1.0.0.RC3/tck). If you have an issue with any of the above, please take a look at [closed issues](https://github.com/reactive-streams/reactive-streams/issues?page=1&state=closed) and then open a [new issue](https://github.com/reactive-streams/reactive-streams/issues/new) if it has not already been answered. |
| 82 | +To get started implementing the draft specification, it is recommended to start by reading the [README](https://github.com/reactive-streams/reactive-streams-jvm/blob/v1.0.0.RC3/README.md), then taking a look at the [Specification](https://github.com/reactive-streams/reactive-streams-jvm/blob/v1.0.0.RC3/README.md#specification) then taking a look at the [TCK](https://github.com/reactive-streams/reactive-streams-jvm/tree/v1.0.0.RC3/tck). If you have an issue with any of the above, please take a look at [closed issues](https://github.com/reactive-streams/reactive-streams/issues?page=1&state=closed) and then open a [new issue](https://github.com/reactive-streams/reactive-streams/issues/new) if it has not already been answered. |
0 commit comments