io.reactivex.flowable.processors.ReplayProcessor Maven / Gradle / Ivy
Show all versions of rxjava3-flowable Show documentation
/**
* Copyright (c) 2016-present, RxJava Contributors.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
* compliance with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License is
* distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
* the License for the specific language governing permissions and limitations under the License.
*/
package io.reactivex.flowable.processors;
import java.lang.reflect.Array;
import java.util.*;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.*;
import org.reactivestreams.*;
import io.reactivex.common.*;
import io.reactivex.common.annotations.CheckReturnValue;
import io.reactivex.common.internal.functions.ObjectHelper;
import io.reactivex.flowable.internal.subscriptions.SubscriptionHelper;
import io.reactivex.flowable.internal.utils.*;
/**
* Replays events to Subscribers.
*
*
*
*
* The ReplayProcessor can be created in bounded and unbounded mode. It can be bounded by
* size (maximum number of elements retained at most) and/or time (maximum age of elements replayed).
*
*
This Processor respects the backpressure behavior of its Subscribers (individually) but
* does not coordinate their request amounts towards the upstream (because there might not be any).
*
*
Note that Subscribers receive a continuous sequence of values after they subscribed even
* if an individual item gets delayed due to backpressure.
*
*
* Example usage:
*
*
{@code
ReplayProcessor
*
* @param the value type
*/
public final class ReplayProcessor extends FlowableProcessor {
/** An empty array to avoid allocation in getValues(). */
private static final Object[] EMPTY_ARRAY = new Object[0];
final ReplayBuffer buffer;
boolean done;
final AtomicReference[]> subscribers;
@SuppressWarnings("rawtypes")
static final ReplaySubscription[] EMPTY = new ReplaySubscription[0];
@SuppressWarnings("rawtypes")
static final ReplaySubscription[] TERMINATED = new ReplaySubscription[0];
/**
* Creates an unbounded ReplayProcessor.
*
* The internal buffer is backed by an {@link ArrayList} and starts with an initial capacity of 16. Once the
* number of items reaches this capacity, it will grow as necessary (usually by 50%). However, as the
* number of items grows, this causes frequent array reallocation and copying, and may hurt performance
* and latency. This can be avoided with the {@link #create(int)} overload which takes an initial capacity
* parameter and can be tuned to reduce the array reallocation frequency as needed.
*
* @param
* the type of items observed and emitted by the ReplayProcessor
* @return the created ReplayProcessor
*/
@CheckReturnValue
public static ReplayProcessor create() {
return new ReplayProcessor(new UnboundedReplayBuffer(16));
}
/**
* Creates an unbounded ReplayProcessor with the specified initial buffer capacity.
*
* Use this method to avoid excessive array reallocation while the internal buffer grows to accommodate new
* items. For example, if you know that the buffer will hold 32k items, you can ask the
* {@code ReplayProcessor} to preallocate its internal array with a capacity to hold that many items. Once
* the items start to arrive, the internal array won't need to grow, creating less garbage and no overhead
* due to frequent array-copying.
*
* @param
* the type of items observed and emitted by the Subject
* @param capacityHint
* the initial buffer capacity
* @return the created subject
*/
@CheckReturnValue
public static ReplayProcessor create(int capacityHint) {
return new ReplayProcessor(new UnboundedReplayBuffer(capacityHint));
}
/**
* Creates a size-bounded ReplayProcessor.
*
* In this setting, the {@code ReplayProcessor} holds at most {@code size} items in its internal buffer and
* discards the oldest item.
*
* When observers subscribe to a terminated {@code ReplayProcessor}, they are guaranteed to see at most
* {@code size} {@code onNext} events followed by a termination event.
*
* If an observer subscribes while the {@code ReplayProcessor} is active, it will observe all items in the
* buffer at that point in time and each item observed afterwards, even if the buffer evicts items due to
* the size constraint in the mean time. In other words, once an Observer subscribes, it will receive items
* without gaps in the sequence.
*
* @param
* the type of items observed and emitted by the Subject
* @param maxSize
* the maximum number of buffered items
* @return the created subject
*/
@CheckReturnValue
public static ReplayProcessor createWithSize(int maxSize) {
return new ReplayProcessor(new SizeBoundReplayBuffer(maxSize));
}
/**
* Creates an unbounded ReplayProcessor with the bounded-implementation for testing purposes.
*
* This variant behaves like the regular unbounded {@code ReplayProcessor} created via {@link #create()} but
* uses the structures of the bounded-implementation. This is by no means intended for the replacement of
* the original, array-backed and unbounded {@code ReplayProcessor} due to the additional overhead of the
* linked-list based internal buffer. The sole purpose is to allow testing and reasoning about the behavior
* of the bounded implementations without the interference of the eviction policies.
*
* @param
* the type of items observed and emitted by the Subject
* @return the created subject
*/
/* test */ static ReplayProcessor createUnbounded() {
return new ReplayProcessor(new SizeBoundReplayBuffer(Integer.MAX_VALUE));
}
/**
* Creates a time-bounded ReplayProcessor.
*
* In this setting, the {@code ReplayProcessor} internally tags each observed item with a timestamp value
* supplied by the {@link Scheduler} and keeps only those whose age is less than the supplied time value
* converted to milliseconds. For example, an item arrives at T=0 and the max age is set to 5; at T>=5
* this first item is then evicted by any subsequent item or termination event, leaving the buffer empty.
*
* Once the subject is terminated, observers subscribing to it will receive items that remained in the
* buffer after the terminal event, regardless of their age.
*
* If an observer subscribes while the {@code ReplayProcessor} is active, it will observe only those items
* from within the buffer that have an age less than the specified time, and each item observed thereafter,
* even if the buffer evicts items due to the time constraint in the mean time. In other words, once an
* observer subscribes, it observes items without gaps in the sequence except for any outdated items at the
* beginning of the sequence.
*
* Note that terminal notifications ({@code onError} and {@code onComplete}) trigger eviction as well. For
* example, with a max age of 5, the first item is observed at T=0, then an {@code onComplete} notification
* arrives at T=10. If an observer subscribes at T=11, it will find an empty {@code ReplayProcessor} with just
* an {@code onComplete} notification.
*
* @param
* the type of items observed and emitted by the Subject
* @param maxAge
* the maximum age of the contained items
* @param unit
* the time unit of {@code time}
* @param scheduler
* the {@link Scheduler} that provides the current time
* @return the created subject
*/
@CheckReturnValue
public static ReplayProcessor createWithTime(long maxAge, TimeUnit unit, Scheduler scheduler) {
return new ReplayProcessor(new SizeAndTimeBoundReplayBuffer(Integer.MAX_VALUE, maxAge, unit, scheduler));
}
/**
* Creates a time- and size-bounded ReplayProcessor.
*
* In this setting, the {@code ReplayProcessor} internally tags each received item with a timestamp value
* supplied by the {@link Scheduler} and holds at most {@code size} items in its internal buffer. It evicts
* items from the start of the buffer if their age becomes less-than or equal to the supplied age in
* milliseconds or the buffer reaches its {@code size} limit.
*
* When observers subscribe to a terminated {@code ReplayProcessor}, they observe the items that remained in
* the buffer after the terminal notification, regardless of their age, but at most {@code size} items.
*
* If an observer subscribes while the {@code ReplayProcessor} is active, it will observe only those items
* from within the buffer that have age less than the specified time and each subsequent item, even if the
* buffer evicts items due to the time constraint in the mean time. In other words, once an observer
* subscribes, it observes items without gaps in the sequence except for the outdated items at the beginning
* of the sequence.
*
* Note that terminal notifications ({@code onError} and {@code onComplete}) trigger eviction as well. For
* example, with a max age of 5, the first item is observed at T=0, then an {@code onComplete} notification
* arrives at T=10. If an observer subscribes at T=11, it will find an empty {@code ReplayProcessor} with just
* an {@code onComplete} notification.
*
* @param
* the type of items observed and emitted by the Subject
* @param maxAge
* the maximum age of the contained items
* @param unit
* the time unit of {@code time}
* @param maxSize
* the maximum number of buffered items
* @param scheduler
* the {@link Scheduler} that provides the current time
* @return the created subject
*/
@CheckReturnValue
public static ReplayProcessor createWithTimeAndSize(long maxAge, TimeUnit unit, Scheduler scheduler, int maxSize) {
return new ReplayProcessor(new SizeAndTimeBoundReplayBuffer(maxSize, maxAge, unit, scheduler));
}
/**
* Constructs a ReplayProcessor with the given custom ReplayBuffer instance.
* @param buffer the ReplayBuffer instance, not null (not verified)
*/
@SuppressWarnings("unchecked")
ReplayProcessor(ReplayBuffer buffer) {
this.buffer = buffer;
this.subscribers = new AtomicReference[]>(EMPTY);
}
@Override
protected void subscribeActual(Subscriber super T> s) {
ReplaySubscription rs = new ReplaySubscription(s, this);
s.onSubscribe(rs);
if (add(rs)) {
if (rs.cancelled) {
remove(rs);
return;
}
}
buffer.replay(rs);
}
@Override
public void onSubscribe(Subscription s) {
if (done) {
s.cancel();
return;
}
s.request(Long.MAX_VALUE);
}
@Override
public void onNext(T t) {
if (t == null) {
onError(new NullPointerException("onNext called with null. Null values are generally not allowed in 2.x operators and sources."));
return;
}
if (done) {
return;
}
ReplayBuffer b = buffer;
b.add(t);
for (ReplaySubscription rs : subscribers.get()) {
b.replay(rs);
}
}
@SuppressWarnings("unchecked")
@Override
public void onError(Throwable t) {
if (t == null) {
t = new NullPointerException("onError called with null. Null values are generally not allowed in 2.x operators and sources.");
}
if (done) {
RxJavaCommonPlugins.onError(t);
return;
}
done = true;
Object o = NotificationLite.error(t);
ReplayBuffer b = buffer;
b.addFinal(o);
for (ReplaySubscription rs : subscribers.getAndSet(TERMINATED)) {
b.replay(rs);
}
}
@SuppressWarnings("unchecked")
@Override
public void onComplete() {
if (done) {
return;
}
done = true;
Object o = NotificationLite.complete();
ReplayBuffer b = buffer;
b.addFinal(o);
for (ReplaySubscription rs : subscribers.getAndSet(TERMINATED)) {
b.replay(rs);
}
}
@Override
public boolean hasSubscribers() {
return subscribers.get().length != 0;
}
/* test */ int subscriberCount() {
return subscribers.get().length;
}
@Override
public Throwable getThrowable() {
Object o = buffer.get();
if (NotificationLite.isError(o)) {
return NotificationLite.getError(o);
}
return null;
}
/**
* Returns a single value the Subject currently has or null if no such value exists.
* The method is thread-safe.
* @return a single value the Subject currently has or null if no such value exists
*/
public T getValue() {
return buffer.getValue();
}
/**
* Returns an Object array containing snapshot all values of the Subject.
*
The method is thread-safe.
* @return the array containing the snapshot of all values of the Subject
*/
public Object[] getValues() {
@SuppressWarnings("unchecked")
T[] a = (T[])EMPTY_ARRAY;
T[] b = getValues(a);
if (b == EMPTY_ARRAY) {
return new Object[0];
}
return b;
}
/**
* Returns a typed array containing a snapshot of all values of the Subject.
*
The method follows the conventions of Collection.toArray by setting the array element
* after the last value to null (if the capacity permits).
*
The method is thread-safe.
* @param array the target array to copy values into if it fits
* @return the given array if the values fit into it or a new array containing all values
*/
public T[] getValues(T[] array) {
return buffer.getValues(array);
}
@Override
public boolean hasComplete() {
Object o = buffer.get();
return NotificationLite.isComplete(o);
}
@Override
public boolean hasThrowable() {
Object o = buffer.get();
return NotificationLite.isError(o);
}
/**
* Returns true if the subject has any value.
*
The method is thread-safe.
* @return true if the subject has any value
*/
public boolean hasValue() {
return buffer.size() != 0; // NOPMD
}
/* test*/ int size() {
return buffer.size();
}
boolean add(ReplaySubscription rs) {
for (;;) {
ReplaySubscription[] a = subscribers.get();
if (a == TERMINATED) {
return false;
}
int len = a.length;
@SuppressWarnings("unchecked")
ReplaySubscription[] b = new ReplaySubscription[len + 1];
System.arraycopy(a, 0, b, 0, len);
b[len] = rs;
if (subscribers.compareAndSet(a, b)) {
return true;
}
}
}
@SuppressWarnings("unchecked")
void remove(ReplaySubscription rs) {
for (;;) {
ReplaySubscription[] a = subscribers.get();
if (a == TERMINATED || a == EMPTY) {
return;
}
int len = a.length;
int j = -1;
for (int i = 0; i < len; i++) {
if (a[i] == rs) {
j = i;
break;
}
}
if (j < 0) {
return;
}
ReplaySubscription[] b;
if (len == 1) {
b = EMPTY;
} else {
b = new ReplaySubscription[len - 1];
System.arraycopy(a, 0, b, 0, j);
System.arraycopy(a, j + 1, b, j, len - j - 1);
}
if (subscribers.compareAndSet(a, b)) {
return;
}
}
}
/**
* Abstraction over a buffer that receives events and replays them to
* individual Subscribers.
*
* @param the value type
*/
interface ReplayBuffer {
void add(T value);
void addFinal(Object notificationLite);
void replay(ReplaySubscription rs);
int size();
T getValue();
T[] getValues(T[] array);
/**
* Returns the terminal NotificationLite object or null if not yet terminated.
* @return the terminal NotificationLite object or null if not yet terminated
*/
Object get();
}
static final class ReplaySubscription extends AtomicInteger implements Subscription {
private static final long serialVersionUID = 466549804534799122L;
final Subscriber super T> actual;
final ReplayProcessor state;
Object index;
final AtomicLong requested;
volatile boolean cancelled;
ReplaySubscription(Subscriber super T> actual, ReplayProcessor state) {
this.actual = actual;
this.state = state;
this.requested = new AtomicLong();
}
@Override
public void request(long n) {
if (SubscriptionHelper.validate(n)) {
BackpressureHelper.add(requested, n);
state.buffer.replay(this);
}
}
@Override
public void cancel() {
if (!cancelled) {
cancelled = true;
state.remove(this);
}
}
}
static final class UnboundedReplayBuffer
extends AtomicReference