Package com.apple.foundationdb.record.provider.foundationdb.cursors

Class UnorderedUnionCursor<T>

  • Type Parameters:
    T - the type of elements returned by the cursor
    All Implemented Interfaces:
    RecordCursor<T>, AutoCloseable, Iterator<T>
    @API(EXPERIMENTAL)
public class UnorderedUnionCursor<T>
extends Object
    A cursor that returns the results of two or more cursors that may return elements in any order. This cursor makes no guarantees as to the order of elements it returns, and it may return the same element more than once as it does not make any attempt to de-duplicate elements that appear in multiple of its source cursors. It attempts to return elements from its children "as they come", which means that it might be the case that identical cursors of this type may return results in two different orders even if all of its child cursors all return the same results if different children happen to be faster in one run than the other (due to, for example, non-determinism in sending messages across the network).

    If there are limits applied to the children of this cursor, this cursor will continue to emit elements as long as there remains at least one child cursor who has not yet returned its last result. (For example, if this cursor has two children and one of them completes faster than the other due to hitting some limit, then the union cursor will continue returning results from the other cursor.) This differs from the behavior of the ordered UnionCursor.

    • Method Detail

      • create

        @Nonnull
public static <T> UnorderedUnionCursor<T> create​(@Nonnull
                                                 List<Function<byte[],​RecordCursor<T>>> cursorFunctions,
                                                 @Nullable
                                                 byte[] continuation,
                                                 @Nullable
                                                 FDBStoreTimer timer)
        Create a union cursor from two or more cursors. Unlike the other UnionCursor, this does not require that the child cursors return values in any particular order. The trade-off, however, is that this cursor will not attempt to remove any duplicates from its children. It will return results from its children as they become available.
        Type Parameters:
        T - the type of elements returned by this cursor
        Parameters:
        cursorFunctions - a list of functions to produce RecordCursors from a continuation
        continuation - any continuation from a previous scan
        timer - the timer used to instrument events
        Returns:
        a cursor containing any records from any child cursor

      • mergeNoNextReasons

        @Nonnull
protected RecordCursor.NoNextReason mergeNoNextReasons()
        Merges all of the cursors and whether they have stopped and returns the "strongest" reason for the result to stop. It will return an out-of-band reason if any of the children stopped for an out-of-band reason, and it will only return SOURCE_EXHAUSTED if all of the cursors are exhausted.
        Returns:
        the strongest reason for stopping

      • onNext

        @Nonnull
public CompletableFuture<RecordCursorResult<U>> onNext()
        Description copied from interface: RecordCursor
        Asynchronously return the next result from this cursor. When complete, the future will contain a RecordCursorResult, which represents exactly one of the following:
        1. The next object of type T produced by the cursor. In addition to the next record, this result includes a RecordCursorContinuation that can be used to continue the cursor after the last record returned. The returned continuation is guaranteed not to be an "end continuation" representing the end of the cursor: specifically, RecordCursorContinuation.isEnd() is always false on the returned continuation.
        2. The fact that the cursor is stopped and cannot produce another record and a RecordCursor.NoNextReason that explains why no record could be produced. The result include a continuation that can be used to continue the cursor after the last record returned. If the result's NoNextReason is anything other than RecordCursor.NoNextReason.SOURCE_EXHAUSTED, the returned continuation must not be an end continuation. Conversely, if the result's NoNextReason is SOURCE_EXHAUSTED, then the returned continuation must be an an "end continuation".
        In either case, the returned RecordCursorContinuation can be serialized to an opaque byte array using RecordCursorContinuation.toBytes(). This can be passed back into a new cursor of the same type, with all other parameters remaining the same.
        Specified by:
        onNext in interface RecordCursor<T>
        Returns:
        a future for the next result from this cursor representing either the next record or an indication of why the cursor stopped
        See Also:
        RecordCursorResult, RecordCursorContinuation

      • getContinuation

        @Nullable
@Deprecated
public byte[] getContinuation()
        Deprecated.
        Description copied from interface: RecordCursor
        Get a byte string that can be used to continue a query after the last record returned.
        Specified by:
        getContinuation in interface RecordCursor<T>
        Returns:
        opaque byte array denoting where the cursor should pick up. This can be passed back into a new cursor of the same type, with all other parameters remaining the same. Returns null if the underlying source is completely exhausted, independent of any limit passed to the cursor creator. Since such creators generally accept null to mean no continuation, that is, start from the beginning, one must check for null from getContinuation to keep from starting over. Result is not always defined if called before onHasNext or before next after onHasNext has returned true. That is, a continuation is only guaranteed when called "between" records from a while (hasNext) next loop or after its end.

      • accept

        public boolean accept​(@Nonnull
                      RecordCursorVisitor visitor)
        Description copied from interface: RecordCursor
        Accept a visit from hierarchical visitor, which implements RecordCursorVisitor. By contract, implementations of this method must return the value of visitor.visitLeave(this), which determines whether or not subsequent siblings of this cursor should be visited.
        Specified by:
        accept in interface RecordCursor<T>
        Parameters:
        visitor - a hierarchical visitor
        Returns:
        true if the subsequent siblings of the cursor should be visited, and false otherwise