/* * 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.rxjava3.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.rxjava3.annotations.*; import io.reactivex.rxjava3.core.Scheduler; import io.reactivex.rxjava3.internal.functions.ObjectHelper; import io.reactivex.rxjava3.internal.subscriptions.SubscriptionHelper; import io.reactivex.rxjava3.internal.util.*; import io.reactivex.rxjava3.plugins.RxJavaPlugins; /** * Replays events to Subscribers. *
* The {@code ReplayProcessor} supports the following item retention strategies: *
*
*
*
*
*
*
*
*
*
*
* The {@code 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). *
* Since a {@code ReplayProcessor} is a Reactive Streams {@code Processor}, * {@code null}s are not allowed (Rule 2.13) as * parameters to {@link #onNext(Object)} and {@link #onError(Throwable)}. Such calls will result in a * {@link NullPointerException} being thrown and the processor's state is not changed. *
* This {@code ReplayProcessor} respects the individual backpressure behavior of its {@code Subscriber}s but * does not coordinate their request amounts towards the upstream (because there might not be any) and * consumes the upstream in an unbounded manner (requesting {@link Long#MAX_VALUE}). * Note that {@code Subscriber}s receive a continuous sequence of values after they subscribed even * if an individual item gets delayed due to backpressure. * Due to concurrency requirements, a size-bounded {@code ReplayProcessor} may hold strong references to more source * emissions than specified. *
* When this {@code ReplayProcessor} is terminated via {@link #onError(Throwable)} or {@link #onComplete()}, * late {@link Subscriber}s will receive the retained/cached items first (if any) followed by the respective * terminal event. If the {@code ReplayProcessor} has a time-bound, the age of the retained/cached items are still considered * when replaying and thus it may result in no items being emitted before the terminal event. *
* Once an {@code Subscriber} has subscribed, it will receive items continuously from that point on. Bounds only affect how * many past items a new {@code Subscriber} will receive before it catches up with the live event feed. *
* Even though {@code ReplayProcessor} implements the {@code Subscriber} interface, calling * {@code onSubscribe} is not required (Rule 2.12) * if the processor is used as a standalone source. However, calling {@code onSubscribe} * after the {@code ReplayProcessor} reached its terminal state will result in the * given {@code Subscription} being canceled immediately. *
* Calling {@link #onNext(Object)}, {@link #onError(Throwable)} and {@link #onComplete()} * is required to be serialized (called from the same thread or called non-overlappingly from different threads * through external means of serialization). The {@link #toSerialized()} method available to all {@code FlowableProcessor}s * provides such serialization and also protects against reentrance (i.e., when a downstream {@code Subscriber} * consuming this processor also wants to call {@link #onNext(Object)} on this processor recursively). *
* This {@code ReplayProcessor} supports the standard state-peeking methods {@link #hasComplete()}, {@link #hasThrowable()}, * {@link #getThrowable()} and {@link #hasSubscribers()} as well as means to read the retained/cached items * in a non-blocking and thread-safe manner via {@link #hasValue()}, {@link #getValue()}, * {@link #getValues()} or {@link #getValues(Object[])}. *
* Note that due to concurrency requirements, a size- and time-bounded {@code ReplayProcessor} may hold strong references to more * source emissions than specified while it isn't terminated yet. Use the {@link #cleanupBuffer()} to allow * such inaccessible items to be cleaned up by GC once no consumer references them anymore. *
* Example usage: *
{@code
ReplayProcessor
*
* @param
* 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
* 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
* In this setting, the {@code ReplayProcessor} holds at most {@code size} items in its internal buffer and
* discards the oldest item.
*
* When {@code Subscriber}s subscribe to a terminated {@code ReplayProcessor}, they are guaranteed to see at most
* {@code size} {@code onNext} events followed by a termination event.
*
* If a {@code Subscriber} 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 a {@code Subscriber} subscribes, it will receive items
* without gaps in the sequence.
*
* @param
* 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
* 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 processor is terminated, {@code Subscriber}s subscribing to it will receive items that remained in the
* buffer after the terminal event, regardless of their age.
*
* If a {@code Subscriber} 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 a
* {@code Subscriber} 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 a {@code Subscriber} subscribes at T=11, it will find an empty {@code ReplayProcessor} with just
* an {@code onComplete} notification.
*
* @param
* 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 {@code Subscriber}s 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 a {@code Subscriber} 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 a {@code Subscriber}
* 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 a {@code Subscriber} subscribes at T=11, it will find an empty {@code ReplayProcessor} with just
* an {@code onComplete} notification.
*
* @param
* By default, live bounded buffers will remember one item before
* the currently receivable one to ensure subscribers can always
* receive a continuous sequence of items. A terminated ReplayProcessor
* automatically releases this inaccessible item.
*
* The method must be called sequentially, similar to the standard
* {@code onXXX} methods.
* History: 2.1.11 - experimental
* @since 2.2
*/
public void cleanupBuffer() {
buffer.trimHead();
}
/**
* Returns the latest value this processor has or null if no such value exists.
* The method is thread-safe.
* @return the latest value this processor currently has or null if no such value exists
*/
@CheckReturnValue
public T getValue() {
return buffer.getValue();
}
/**
* Returns an Object array containing snapshot all values of this processor.
* The method is thread-safe.
* @return the array containing the snapshot of all values of this processor
*/
@CheckReturnValue
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 this processor.
* 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
*/
@CheckReturnValue
public T[] getValues(T[] array) {
return buffer.getValues(array);
}
@Override
@CheckReturnValue
public boolean hasComplete() {
ReplayBuffer The method is thread-safe.
* @return true if the processor has any value
*/
@CheckReturnValue
public boolean hasValue() {
return buffer.size() != 0; // NOPMD
}
@CheckReturnValue
/* test*/ int size() {
return buffer.size();
}
boolean add(ReplaySubscription