# Flow

public final class **Flow** extends [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html)  
Interrelated interfaces and static methods for establishing
flow-controlled components in which `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.Publisher.html`
produce items consumed by one or more `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.Subscriber.html`, each managed by a `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.Subscription.html`.

These interfaces correspond to the [reactive-streams](http://www.reactive-streams.org/)
specification. They apply in both concurrent and distributed
asynchronous settings: All (seven) methods are defined in `void` "one-way" message style. Communication relies on a simple form
of flow control (method `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.Subscription.html#request(long)`) that can be
used to avoid resource management problems that may otherwise occur
in "push" based systems.

**Examples.** A `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.Publisher.html` usually defines its own
`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.Subscription.html` implementation; constructing one in method
`subscribe` and issuing it to the calling `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.Subscriber.html`. It publishes items to the subscriber asynchronously,
normally using an `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Executor.html`. For example, here is a very
simple publisher that only issues (when requested) a single `TRUE` item to a single subscriber. Because the subscriber receives
only a single item, this class does not use buffering and ordering
control required in most implementations.

     class OneShotPublisher implements Publisher<Boolean> {
       private final ExecutorService executor = ForkJoinPool.commonPool(); // daemon-based
       private boolean subscribed; // true after first subscribe
       public synchronized void subscribe(Subscriber<? super Boolean> subscriber) {
         if (subscribed)
           subscriber.onError(new IllegalStateException()); // only one allowed
         else {
           subscribed = true;
           subscriber.onSubscribe(new OneShotSubscription(subscriber, executor));
         }
       }
       static class OneShotSubscription implements Subscription {
         private final Subscriber<? super Boolean> subscriber;
         private final ExecutorService executor;
         private Future<?> future; // to allow cancellation
         private boolean completed;
         OneShotSubscription(Subscriber<? super Boolean> subscriber,
                             ExecutorService executor) {
           this.subscriber = subscriber;
           this.executor = executor;
         }
         public synchronized void request(long n) {
           if (n != 0 && !completed) {
             completed = true;
             if (n < 0) {
               IllegalArgumentException ex = new IllegalArgumentException();
               executor.execute(() -> subscriber.onError(ex));
             } else {
               future = executor.submit(() -> {
                 subscriber.onNext(Boolean.TRUE);
                 subscriber.onComplete();
               });
             }
           }
         }
         public synchronized void cancel() {
           completed = true;
           if (future != null) future.cancel(false);
         }
       }
     }

A `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.Subscriber.html` arranges that items be requested and
processed. Items (invocations of `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.Subscriber.html#onNext(T)`) are
not issued unless requested, but multiple items may be requested.
Many Subscriber implementations can arrange this in the style of
the following example, where a buffer size of 1 single-steps, and
larger sizes usually allow for more efficient overlapped processing
with less communication; for example with a value of 64, this keeps
total outstanding requests between 32 and 64.
Because Subscriber method invocations for a given `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.Subscription.html` are strictly ordered, there is no need for these
methods to use locks or volatiles unless a Subscriber maintains
multiple Subscriptions (in which case it is better to instead
define multiple Subscribers, each with its own Subscription).

     class SampleSubscriber<T> implements Subscriber<T> {
       final Consumer<? super T> consumer;
       Subscription subscription;
       final long bufferSize;
       long count;
       SampleSubscriber(long bufferSize, Consumer<? super T> consumer) {
         this.bufferSize = bufferSize;
         this.consumer = consumer;
       }
       public void onSubscribe(Subscription subscription) {
         long initialRequestSize = bufferSize;
         count = bufferSize - bufferSize / 2; // re-request when half consumed
         (this.subscription = subscription).request(initialRequestSize);
       }
       public void onNext(T item) {
         if (--count <= 0)
           subscription.request(count = bufferSize - bufferSize / 2);
         consumer.accept(item);
       }
       public void onError(Throwable ex) { ex.printStackTrace(); }
       public void onComplete() {}
     }

The default value of `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.html#defaultBufferSize()` may provide a
useful starting point for choosing request sizes and capacities in
Flow components based on expected rates, resources, and usages.
Or, when flow control is never needed, a subscriber may initially
request an effectively unbounded number of items, as in:

     class UnboundedSubscriber<T> implements Subscriber<T> {
       public void onSubscribe(Subscription subscription) {
         subscription.request(Long.MAX_VALUE); // effectively unbounded
       }
       public void onNext(T item) { use(item); }
       public void onError(Throwable ex) { ex.printStackTrace(); }
       public void onComplete() {}
       void use(T item) { ... }
     }

<br />

### Nested Class Summary

|---|---|---|---|
| interface | [Flow.Processor](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.Processor.html)\<T, R\> || A component that acts as both a Subscriber and Publisher. |
| interface | [Flow.Publisher](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.Publisher.html)\<T\> || A producer of items (and related control messages) received by Subscribers. |
| interface | [Flow.Subscriber](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.Subscriber.html)\<T\> || A receiver of messages. |
| interface | [Flow.Subscription](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.Subscription.html) || Message control linking a `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.Publisher.html` and `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.Subscriber.html`. |

### Public Method Summary

|---|---|
| static int | [defaultBufferSize](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Flow.html#defaultBufferSize())() Returns a default value for Publisher or Subscriber buffering, that may be used in the absence of other constraints. |

### Inherited Method Summary

From class [java.lang.Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html)

|---|---|
| [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) | [clone](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#clone())() Creates and returns a copy of this `Object`. |
| boolean | [equals](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#equals(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) obj) Compares this instance with the specified object and indicates if they are equal. |
| void | [finalize](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#finalize())() Invoked when the garbage collector has detected that this instance is no longer reachable. |
| final [Class](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Class.html)\<?\> | [getClass](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#getClass())() Returns the unique instance of `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Class.html` that represents this object's class. |
| int | [hashCode](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#hashCode())() Returns an integer hash code for this object. |
| final void | [notify](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#notify())() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up. |
| final void | [notifyAll](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#notifyAll())() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up. |
| [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) | [toString](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#toString())() Returns a string containing a concise, human-readable description of this object. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait(long,%20int))(long timeout, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait(long))(long timeout) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait())() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object. |

## Public Methods

#### public static int
**defaultBufferSize**
()

Returns a default value for Publisher or Subscriber buffering,
that may be used in the absence of other constraints.

##### Returns

- the buffer size value