simple react streams overview

What is simple-react

simple-react is a set of 3 Streams / Stream-like structures for different Java 8 use cases. They are

1. SimpleReactStream
2. LazyFutureStream
3. ReactiveSeq

LazyFutureStream

Provides a more advanced Stream-api over a custom Fast Future implementation. Particularly suited for advanced operations on data captured / retrieved via blocking I/O. Tasks that can be executed independently of each data element are handled by the Futures as per SimpleReact. Streaming tasks (such as windowing) that require access to a sequential Stream of data push results from each Future Task to a wait-free queue, from which data can be sequentially Streamed before being distributed across threads to the next set of FastFuture tasks.

LazyFutureStream implements the reactive-streams api can be either a reactive-streams publisher or subscriber.

LazyFutureStream extends ReactiveSeq which in turn extends jOOλ Seq which in turn extends java.util.stream.Stream

ReactiveSeq

Provides the same advanced Stream-api but implemented as a pure, fast, single-threaded Stream that is suitable for typical CPU bound Stream operations. ReactiveSeq Streams can be executed on the current thread or asynchronously on a targeted alternative thread.

Stream type overview

FEATURE	SimpleReact	ReactiveSeq	LazyFutureStream	JDK 8 Stream (sequential)	JDK 8 Stream (parallel)
Multithreading	Yes	No	Yes	No	Yes
Optimized for multithreaded blocking I/O	Yes	No	Yes	No	No
Optimized for CPU bound operations	No	Yes	No	Yes	Yes
Eager / Lazy	Eager	Lazy	Lazy	Lazy	Lazy
Free-threading (target single thread not current)	Yes	Yes	Yes	No	No (except 'hack')
Target different executors per stage	Yes	No	Yes	No	No
Concurrency configurability	Highly configurable	Yes	Highly configurable	No	Limited
Failure recovery	Yes	Yes	Yes	No	No
Retry support	Yes	Yes	Yes	No	No
Time control	No	Yes	Yes	No	No
Batching / windowing	No	Yes	Yes	No	No
Zipping	Yes	Yes	Yes	No	No
Compatible with SimpleReact async datastructures	Yes	Yes	Yes	No	No
each task can be executed independently	Yes	No	Yes	No	No
async terminal operations	No	Yes	Yes	No	No
implements java.util.stream.Stream	No	Yes	Yes	Yes	Yes
reactive-streams support in simple-react	Yes	Yes	Yes	Yes	Yes
HotStreams support in simple-react	No	Yes	Yes	Yes	Yes

simple-react is a fast Reactive Streams (http://www.reactive-streams.org/) implementation that also implements, and significantly enhances, the JDK 8 Stream interface, to provide powerful asynchronous Streams backed by your choice of wait-free queues (with or without mechanical sympathy) or blocking queues. simple-react reuses standard Java 8 functional interfaces and libraries such as CompletableFuture.

LazyFutureStream pulls 'chains' of asynchronous FastFuture tasks into existance (SimpleReact pull 'chains' of CompletableFutures into existence).

##Stream Types

Asynchronous datastructures

• Queue : async queue that can be used to join producing and consuming streams. Multiple consuming streams (if connected) compete for messages on the queue.

• Topic : async topic that can be used to join producing and consuming streams. Multiple consuming streams (if connected) recieve each message on the topic.

• Signal : async signal that can stream changes, backed by either a Topic or a Queue.

SimpleReact is a parallel Stream library that implements java.util.stream.Stream. Under the hood, SimpleReact manages parallel streams as a stream of CompletableFutures. SimpleReact provides a simple core API based on the Promises / A++ spec, while also providing a full rich range of options by implementing both JDK 8 Stream, and the scala-like jOOλ Seq. SimpleReact goes beyond the traditional Java 8 Streaming interface by offering failure recovery, capture and retry functionality.

It is an easy to use, concurrent, reactive programming library for JDK 8. It provides a focused, simple and limited core Reactive API aimed at solving the 90% use case - but without adding complexity. It is a core goal of SimpleReact to integrate with JDK 8 Stream libraries for maximum reuse and plugability.

See A Simple Api, and a Rich Api for details on SimpleReact core and the java Streaming interfaces.

Getting SimpleReact

• Adding SimpleReact as a dependency
• Search Maven

##Documentation

• Reactive programming with Java 8 and simple-react: The Tutorial
• wiki
• Javadoc
• Articles on medium

##Getting started

• See an illustrative getting started example

• What does Simple React do

• Understanding simple-react pull/push model

Why SimpleReact

Why daisy-chain together CompletableFuture's by hand? SimpleReact allows you to put together sophisticated concurrent chains of CompletableFutures with a very easy to use API.

SimpleReact is built on top of JDK standard libraries and unlike other Reactive implementations for Java, specifically targets JDK 8 and thus reuses rather than reinvents Streams, Functional interfaces etc. SimpleReact augments the parallel Streams functionality in JDK by providing a facade over both the Streams and CompletableFuture apis. Under-the-hood, SimpleReact is a Stream of CompletableFutures, and presents that externally as an api somewhat inspired by the Javascript Promises / A+ Spec (https://promisesaplus.com/).

Everything is concurrent in SimpleReact. While this does limit some of the syntax-sugar we can provide directly, the small & focused SimpleReact Api together with the Apis of the underlying JDK 8 primitives offer often surprising levels of power and flexibility.

• See an example of using CompletableFuture directly with SimpleReact

#SimpleReact Streams and commands

• [List of operators] (https://github.com/aol/simple-react/wiki/A-simple-API,-and-a-Rich-API)
• Batching, control, sharding and zipping operators

##limit

###LazyFutureStream, SimpleReactStream, ReactiveSeq

When a limit is applied to a LazyFutureStream it is applied to the tasks before they start.

##skip

Skip will perform as in the same way as Limit for all three Stream types but skips the first X data points instead.

###LazyFutureStream For LazyFutureStream specifying a skip will skip the first X tasks specified in the previous stage.

##map / then

###EagerFutureStream, LazyFutureStream, SimpleReactStream

For all three Streams map or then converts input data in one format to output data in another.

##retry

###EagerFutureStream, LazyFutureStream, SimpleReactStream

Retry allows a task in a stage to be retried if it fails

##onFail

###LazyFutureStream, SimpleReactStream For all three Streams onFail allows recovery from a Streaming stage that fails.

##capture

LazyFutureStream, SimpleReactStream

Capture allows error handling for unrecoverable errors.

##flatMap

###EagerFutureStream, LazyFutureStream, SimpleReactStream

For all three Streams specifying a flatMap splits a single result into multiple tasks by returning a Stream from the flatMap method.

##allOf (async collect) ###SimpleReactStream

allOf is the inverse of flatMap. It rolls up a Stream from a previous stage, asynchronously into a single collection for further processing as a group.

##anyOf ###SimpleReactStream

anyOf progresses the flow with the first result received.

##block / collect ###ReactiveSeq, LazyFutureStream, SimpleReactStream

Block behaves like allOf except that it blocks the calling thread until the Stream has been processed.

##zip ###ReactiveSeq, LazyFutureStream, SimpleReactStream

Zip merges two streams by taking the next available result from each stream. For SimpleReactStreams the underlying Stream of futures is zipped, connnecting two future objects into a Tuple2.

##toQueue ###LazyFutureStream, SimpleReactStream

toQueue creates a new simplereact.aysnc.Queue that is populated asynchronously by the current Stream. Another Stream (Consumer) can be created from the Queue by calling queue.toStream()

#Choosing A Stream Type

The key components in choosing what type of Stream to create are :

1. Eager or Lazy
2. Multi-threaded blocking I/O or CPU bound tasks
3. What data a stream should be provided with
4. Optimising Stream performance

##Eager Streams and Lazy Streams

SimpleReactStreams can be either Eager or Lazy, by default they are Eager.

Eager Streams start processing immediately, while Lazy Streams start processing when a terminal operation is invoked.

SimpleReact provides builder classes, and JDK 8 Stream style factory methods on the Stream itself that can be used to create appropriate Streams.

*SimpleReact - builder class for SimpleReact

*LazyReact - builder class for LazyFutureStreams