Reactive streams and Flow
suggest changeA reactive stream is an asynchronous sequence of items pushed from a producer to a consumer, with backpressure: the consumer says how many items it can take, and the producer never sends more than that. A fast producer therefore can't flood a slow consumer with an unbounded queue of work.
Reactive Streams is a small specification for this protocol, used by Project Reactor, RxJava, Akka Streams, Mutiny, R2DBC and many reactive drivers. Java 9 copied its four interfaces into the JDK as nested types of java.util.concurrent.Flow, so libraries can interoperate without sharing a dependency.
What the JDK gives you:
- the interfaces
Flow.Publisher,Flow.Subscriber,Flow.SubscriptionandFlow.Processor - one implementation,
SubmissionPublisher, a publisher you push items into java.net.http.HttpClient, which usesFlowfor streaming request and response bodies
There are no operators such as map, filter or merge. For real pipelines you use a library; Flow is the common type at the boundary.
Flow is not the same as java.util.stream.Stream. A Stream is pulled synchronously by one thread through a terminal operation. A Flow.Publisher pushes items, usually on other threads, whenever the subscriber has asked for them. See Streams for the former.
The four interfaces
public final class Flow {
@FunctionalInterface
public interface Publisher<T> {
void subscribe(Subscriber<? super T> subscriber);
}
public interface Subscriber<T> {
void onSubscribe(Subscription subscription);
void onNext(T item);
void onError(Throwable throwable);
void onComplete();
}
public interface Subscription {
void request(long n);
void cancel();
}
public interface Processor<T, R> extends Subscriber<T>, Publisher<R> {}
public static int defaultBufferSize() { ... } // 256
}
The protocol, in short:
- The subscriber calls
publisher.subscribe(subscriber). - The publisher calls
subscriber.onSubscribe(subscription)exactly once. - The subscriber calls
subscription.request(n)to ask fornmore items. Demand adds up;Long.MAX_VALUEmeans "unbounded". - The publisher calls
onNext(item)at most as many times as was requested in total. - The stream ends with exactly one
onComplete()oronError(t). After that, no more signals arrive. - The subscriber may call
cancel()at any time to stop receiving items.
The signals to one subscriber never overlap: onNext is not called again until the previous call returns, and each call happens-before the next. That is why a subscriber can keep its state in plain fields without locks.
Other rules worth knowing: request(n) with n <= 0 must result in onError with an IllegalArgumentException, items and errors must not be null, and subscriber methods should not throw. The full list of about 40 rules is in the specification.
SubmissionPublisher and consume
SubmissionPublisher<T> is a publisher that you feed with submit(item). It keeps a separate buffer for each subscriber and delivers items asynchronously on an Executor (by default ForkJoinPool.commonPool()).
The easiest way to subscribe is consume, which takes a plain Consumer and returns a CompletableFuture<Void> that completes when the stream does:
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.SubmissionPublisher;
var publisher = new SubmissionPublisher<String>();
CompletableFuture<Void> done = publisher.consume(s -> System.out.println("got " + s));
publisher.submit("apple");
publisher.submit("banana");
publisher.submit("cherry");
publisher.close(); // signals onComplete after the buffered items
done.join(); // wait until the subscriber has seen everything
System.out.println("finished");
got apple
got banana
got cherry
finished
Three things to notice:
- Subscribe first, then submit. A subscriber only sees items submitted after it subscribed; there is no replay.
- Wait for completion. Items are delivered on common-pool threads, which are daemon threads. If
mainreturns withoutdone.join(), the JVM can exit before anything is printed. - Always
close()(orcloseExceptionally) the publisher, otherwise subscribers never getonComplete.SubmissionPublisherimplementsAutoCloseable, so try-with-resources works when the publisher's lifetime fits a block.
Writing a Subscriber
Implementing Flow.Subscriber yourself gives you control over demand. This subscriber asks for one item at a time, which is the most conservative form of backpressure:
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.Flow;
class PrintingSubscriber<T> implements Flow.Subscriber<T> {
private final CountDownLatch done = new CountDownLatch(1);
private Flow.Subscription subscription;
@Override
public void onSubscribe(Flow.Subscription subscription) {
this.subscription = subscription;
System.out.println("onSubscribe");
subscription.request(1);
}
@Override
public void onNext(T item) {
System.out.println("onNext " + item);
subscription.request(1); // ready for the next one
}
@Override
public void onError(Throwable throwable) {
System.out.println("onError " + throwable);
done.countDown();
}
@Override
public void onComplete() {
System.out.println("onComplete");
done.countDown();
}
void await() throws InterruptedException {
done.await();
}
}
var publisher = new SubmissionPublisher<Integer>();
var subscriber = new PrintingSubscriber<Integer>();
publisher.subscribe(subscriber);
for (int i = 1; i <= 3; i++) {
publisher.submit(i);
}
publisher.close();
subscriber.await();
onSubscribe
onNext 1
onNext 2
onNext 3
onComplete
Requesting one item at a time costs a little coordination per item. A common optimisation is to request a batch (say 64) and request more once half of it has been processed. If you don't need backpressure at all, request Long.MAX_VALUE in onSubscribe and never call request again.
Backpressure: submit vs offer
Each subscriber has a bounded buffer. Its size is set in the constructor (Flow.defaultBufferSize(), 256, by default; it may be rounded up to a power of two):
var publisher = new SubmissionPublisher<Integer>(ForkJoinPool.commonPool(), 16);
When a subscriber falls behind and its buffer is full, the publisher has to do something. SubmissionPublisher offers three choices:
| Method | When a buffer is full |
|---|---|
submit(item) |
blocks the calling thread until there is room |
offer(item, onDrop) |
doesn't block; calls onDrop and drops the item |
offer(item, timeout, unit, onDrop) |
blocks up to the timeout, then drops |
submit returns an estimate of the largest lag among subscribers. offer returns the same, or a negative number of drops if the item was dropped for some subscriber. The onDrop handler is a BiPredicate<Flow.Subscriber<? super T>, ? super T>; return true to retry once, false to give up.
Here a slow consumer with a 4-item buffer meets a publisher that refuses to wait:
import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicInteger;
static void sleep(long millis) {
try {
Thread.sleep(millis);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}
var publisher = new SubmissionPublisher<Integer>(ForkJoinPool.commonPool(), 4);
var dropped = new AtomicInteger();
CompletableFuture<Void> done = publisher.consume(i -> {
sleep(50); // slow processing
System.out.println("processed " + i);
});
for (int i = 1; i <= 20; i++) {
publisher.offer(i, (subscriber, item) -> {
dropped.incrementAndGet();
return false; // don't retry
});
}
publisher.close();
done.join();
System.out.println("dropped " + dropped.get());
Typical output (the exact numbers depend on timing):
processed 1
processed 2
processed 3
processed 4
dropped 16
With submit instead of offer, all 20 items would be processed and the loop would simply run at the consumer's speed. Which one is right depends on the data: drop stale sensor readings or UI updates, block for orders and log lines.
Note that submit blocks uninterruptibly. Don't call it on a thread that must stay responsive, such as an event loop.
Other useful methods: estimateMaximumLag(), estimateMinimumDemand(), getNumberOfSubscribers(), hasSubscribers() and isClosed().
Cancelling
A subscriber that has seen enough calls cancel(). The publisher stops sending to it and may release its resources; other subscribers are not affected. This subscriber takes the first n items:
class TakeSubscriber implements Flow.Subscriber<Integer> {
private final int limit;
private final CountDownLatch done = new CountDownLatch(1);
private Flow.Subscription subscription;
private int received;
TakeSubscriber(int limit) {
this.limit = limit;
}
@Override
public void onSubscribe(Flow.Subscription subscription) {
this.subscription = subscription;
subscription.request(limit); // we know exactly how many we want
}
@Override
public void onNext(Integer item) {
System.out.println("took " + item);
if (++received == limit) {
subscription.cancel();
done.countDown();
}
}
@Override
public void onError(Throwable t) { done.countDown(); }
@Override
public void onComplete() { done.countDown(); }
void await() throws InterruptedException { done.await(); }
}
var publisher = new SubmissionPublisher<Integer>();
var take = new TakeSubscriber(3);
publisher.subscribe(take);
for (int i = 1; i <= 10; i++) {
publisher.submit(i);
}
take.await();
publisher.close();
took 1
took 2
took 3
After cancellation, items submitted for that subscriber are discarded. Signals already in flight may still arrive after cancel(), so a subscriber must tolerate an extra onNext or two.
Processors: building a pipeline
A Flow.Processor<T, R> is both a subscriber of T and a publisher of R, i.e. a stage in a pipeline. The simplest way to write one is to extend SubmissionPublisher<R>, which takes care of the publishing half:
import java.util.concurrent.Flow;
import java.util.concurrent.SubmissionPublisher;
import java.util.function.Function;
class MapProcessor<T, R> extends SubmissionPublisher<R>
implements Flow.Processor<T, R> {
private final Function<? super T, ? extends R> function;
private Flow.Subscription subscription;
MapProcessor(Function<? super T, ? extends R> function) {
this.function = function;
}
@Override
public void onSubscribe(Flow.Subscription subscription) {
this.subscription = subscription;
subscription.request(1);
}
@Override
public void onNext(T item) {
R result;
try {
result = function.apply(item);
} catch (RuntimeException e) {
subscription.cancel();
closeExceptionally(e); // downstream gets onError
return;
}
submit(result); // blocks if downstream is full
subscription.request(1);
}
@Override
public void onError(Throwable throwable) {
closeExceptionally(throwable);
}
@Override
public void onComplete() {
close();
}
}
Backpressure propagates up the chain on its own: when the downstream buffer is full, submit blocks, so this stage stops requesting, so its upstream buffer fills, and so on back to the source.
Wire the stages together from the end towards the source, then start feeding it:
var source = new SubmissionPublisher<String>();
var parse = new MapProcessor<String, Integer>(Integer::parseInt);
var square = new MapProcessor<Integer, Integer>(n -> n * n);
source.subscribe(parse);
parse.subscribe(square);
CompletableFuture<Void> done = square.consume(n -> System.out.println("result " + n));
for (String s : List.of("1", "2", "3", "4")) {
source.submit(s);
}
source.close();
done.join();
result 1
result 4
result 9
result 16
close() on the source travels down the pipeline as onComplete, each stage closes itself, and finally the future returned by consume completes.
Errors
An error is a terminal signal, just like completion. closeExceptionally(t) on a SubmissionPublisher delivers onError(t) to every subscriber, and in the pipeline above a failing function does the same. With the same pipeline and the input "1", "two", "3":
try {
done.join();
} catch (CompletionException e) {
System.out.println("failed: " + e.getCause());
}
failed: java.lang.NumberFormatException: For input string: "two"
Unlike close(), closeExceptionally doesn't wait for buffered items to drain: the error can overtake items still sitting in a subscriber's buffer. Here result 1 was overtaken and never printed; with different timing it may appear. If every item before the failure must be processed, the error has to travel as data (for example a result type holding either a value or an exception) rather than as onError.
If the Consumer passed to consume throws, the subscription is cancelled and the returned future completes exceptionally with that exception.
A plain Subscriber whose onNext throws is a broken subscriber: SubmissionPublisher cancels its subscription and calls its onError with the exception, but nothing tells the rest of your code. To find out, pass a handler to the constructor:
var publisher = new SubmissionPublisher<Integer>(
ForkJoinPool.commonPool(),
Flow.defaultBufferSize(),
(subscriber, error) -> System.err.println("subscriber failed: " + error));
The handler is called before the subscription is cancelled. Better still, catch exceptions inside onNext and handle them there, as MapProcessor does.
Writing a Publisher from scratch
Writing a correct publisher is harder than it looks: demand from concurrent request calls has to be added up safely, request may be called from inside onNext (re-entrancy), and you must not deliver more than was requested. Here is a minimal synchronous publisher of a range of integers that gets those details right:
import java.util.concurrent.Flow;
import java.util.concurrent.atomic.AtomicLong;
class RangePublisher implements Flow.Publisher<Integer> {
private final int start;
private final int end; // exclusive
RangePublisher(int start, int end) {
this.start = start;
this.end = end;
}
@Override
public void subscribe(Flow.Subscriber<? super Integer> subscriber) {
subscriber.onSubscribe(new RangeSubscription(subscriber, start, end));
}
private static final class RangeSubscription implements Flow.Subscription {
private final Flow.Subscriber<? super Integer> downstream;
private final int end;
private final AtomicLong requested = new AtomicLong();
private volatile boolean cancelled;
private int next;
RangeSubscription(Flow.Subscriber<? super Integer> downstream, int start, int end) {
this.downstream = downstream;
this.next = start;
this.end = end;
}
@Override
public void request(long n) {
if (n <= 0) {
cancel();
downstream.onError(new IllegalArgumentException("request must be > 0, was " + n));
return;
}
// add n to the demand, capping at Long.MAX_VALUE
long before = requested.getAndAccumulate(n,
(cur, add) -> cur + add < 0 ? Long.MAX_VALUE : cur + add);
if (before != 0) {
return; // another call (maybe further up our own stack) is emitting
}
emit();
}
private void emit() {
while (true) {
long demand = requested.get();
long emitted = 0;
while (emitted < demand && next < end) {
if (cancelled) return;
downstream.onNext(next++);
emitted++;
}
if (cancelled) return;
if (next == end) {
cancelled = true;
downstream.onComplete();
return;
}
if (requested.addAndGet(-emitted) == 0) {
return; // no more demand; a later request() restarts us
}
}
}
@Override
public void cancel() {
cancelled = true;
}
}
}
The requested counter does double duty: it holds the outstanding demand, and the thread that moves it away from zero is the only one allowed to emit. A request made from inside onNext just increases the counter and returns, and the running loop picks the extra demand up. That keeps the stack from growing with every item.
A subscriber that asks for two items at a time shows the demand at work:
new RangePublisher(1, 6).subscribe(new Flow.Subscriber<Integer>() {
private Flow.Subscription subscription;
private int received;
@Override
public void onSubscribe(Flow.Subscription s) {
subscription = s;
System.out.println("request(2)");
s.request(2);
}
@Override
public void onNext(Integer item) {
System.out.println("onNext " + item);
if (++received % 2 == 0) {
System.out.println("request(2)");
subscription.request(2);
}
}
@Override
public void onError(Throwable t) { t.printStackTrace(); }
@Override
public void onComplete() { System.out.println("onComplete"); }
});
request(2)
onNext 1
onNext 2
request(2)
onNext 3
onNext 4
request(2)
onNext 5
onComplete
For anything beyond a toy, test your publishers and subscribers against the official TCK (org.reactivestreams:reactive-streams-tck-flow), which checks the specification rules one by one. Or, more realistically, don't write them: use a library.
Flow in HttpClient
java.net.http.HttpClient speaks Flow for streaming bodies. BodyHandlers.ofPublisher() returns the response body as a Flow.Publisher<List<ByteBuffer>>, and data is only read from the network as fast as you request it:
import java.net.URI;
import java.net.http.*;
import java.nio.ByteBuffer;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.Flow;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(URI.create("https://example.com/")).build();
HttpResponse<Flow.Publisher<List<ByteBuffer>>> response =
client.send(request, HttpResponse.BodyHandlers.ofPublisher());
var total = new CompletableFuture<Long>();
response.body().subscribe(new Flow.Subscriber<List<ByteBuffer>>() {
private long bytes;
public void onSubscribe(Flow.Subscription s) { s.request(Long.MAX_VALUE); }
public void onNext(List<ByteBuffer> buffers) {
for (ByteBuffer b : buffers) bytes += b.remaining();
}
public void onError(Throwable t) { total.completeExceptionally(t); }
public void onComplete() { total.complete(bytes); }
});
System.out.println("status " + response.statusCode() + ", " + total.join() + " bytes");
In the other direction, HttpRequest.BodyPublishers.fromPublisher(publisher) uploads a request body from any Flow.Publisher<ByteBuffer>, and HttpResponse.BodySubscribers.fromSubscriber(subscriber) plugs your own subscriber into a response.
Using a reactive library
Real applications use a library that implements the protocol and adds hundreds of operators. Project Reactor (io.projectreactor:reactor-core) and RxJava 3 implement the org.reactivestreams interfaces, which are identical in shape to Flow but are different types. Adapters convert between them:
- Reactor:
reactor.adapter.JdkFlowAdapter.flowPublisherToFlux(...)andpublisherToFlowPublisher(...) - any library:
org.reactivestreams.FlowAdapters.toPublisher(...)andtoFlowPublisher(...)fromorg.reactivestreams:reactive-streams
Our hand-written RangePublisher becomes a full Flux:
import reactor.adapter.JdkFlowAdapter;
import reactor.core.publisher.Flux;
Flux<Integer> numbers = JdkFlowAdapter.flowPublisherToFlux(new RangePublisher(1, 11));
numbers.filter(n -> n % 2 == 0)
.map(n -> n * n)
.subscribe(System.out::println);
4
16
36
64
100
Do you need reactive streams?
Reactive libraries became popular because platform threads are expensive: a server that blocked a thread per request ran out of threads. Since Java 21, virtual threads make blocking cheap, and plain sequential code is easier to write, debug and read in a stack trace than a chain of operators.
Reactive streams still earn their place when:
- the data really is a stream (events, messages, sensor readings, a large download) and you need backpressure between producer and consumer
- you need operators over time: buffering, windowing, throttling, debouncing, merging several sources
- a framework or driver you use is reactive (Spring WebFlux, R2DBC, reactive MongoDB or Kafka clients)
For a single asynchronous result use CompletableFuture instead, and for a simple hand-off between threads a BlockingQueue (see Producer-Consumer) is often enough: a bounded queue is backpressure too.
Summary
java.util.concurrent.Flowholds the Reactive Streams interfaces:Publisher,Subscriber,Subscription,Processor.- The subscriber drives the flow with
request(n); the publisher never sends more than requested. Streams end with oneonCompleteoronError. SubmissionPublisheris the JDK's only implementation. Subscribe before submitting,close()when done, and wait for completion beforemainexits.submitblocks when a subscriber's buffer is full;offerdrops instead.- Extending
SubmissionPublisheris the easiest way to write aProcessor. Catch exceptions inonNextand turn them intocloseExceptionally. - For operators and production use, adopt Reactor or RxJava and convert at the boundary with
JdkFlowAdapterorFlowAdapters.