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

Class UnorderedUnionCursor<T>

java.lang.Object

com.apple.foundationdb.record.provider.foundationdb.cursors.MergeCursor<T,T,S>

com.apple.foundationdb.record.provider.foundationdb.cursors.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 MergeCursor<T,T,S>

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.

Nested Class Summary

Nested classes/interfaces inherited from interface com.apple.foundationdb.record.RecordCursor

RecordCursor.NoNextReason

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	UnorderedUnionCursor(List<MergeCursorState<T>> cursorStates, FDBStoreTimer timer)

Method Summary

Modifier and Type	Method	Description
protected CompletableFuture<List<MergeCursorState<T>>>	computeNextResultStates()	Determine which cursors should have their values included in the next iteration.
static <T> UnorderedUnionCursor<T>	create(List<Function<byte[],RecordCursor<T>>> cursorFunctions, byte[] continuation, FDBStoreTimer timer)	Create a union cursor from two or more cursors.
protected com.apple.foundationdb.record.provider.foundationdb.cursors.UnionCursorContinuation	getContinuationObject()	Produce a RecordCursorContinuation for this cursor.
protected T	getNextResult(List<S> chosenStates)	Get the result from the list of chosen states.
protected RecordCursor.NoNextReason	mergeNoNextReasons()	Merges all of the cursors and whether they have stopped and returns the "strongest" reason for the result to stop.

Methods inherited from class com.apple.foundationdb.record.provider.foundationdb.cursors.MergeCursor

accept, checkNextStateTimeout, close, getChildContinuations, getContinuation, getCursorStates, getExecutor, getNoNextReason, getStrongestNoNextReason, getTimer, getWeakestNoNextReason, next, onHasNext, onNext, whenAll, whenAny

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Iterator

forEachRemaining, remove

Methods inherited from interface com.apple.foundationdb.record.RecordCursor

asIterator, asList, filter, filterAsync, filterAsyncInstrumented, filterAsyncInstrumented, filterInstrumented, filterInstrumented, first, flatMapPipelined, forEach, forEachAsync, forEachResult, forEachResultAsync, getCount, getNext, hasNext, limitRowsTo, limitTo, map, mapEffect, mapEffect, mapPipelined, orElse, reduce, skip, skipThenLimit

Constructor Detail

UnorderedUnionCursor

protected UnorderedUnionCursor(@Nonnull
                               List<MergeCursorState<T>> cursorStates,
                               @Nullable
                               FDBStoreTimer timer)

Method Detail

computeNextResultStates

@Nonnull
protected CompletableFuture<List<MergeCursorState<T>>> computeNextResultStates()

Description copied from class: MergeCursor

Determine which cursors should have their values included in the next iteration. This list should include the state associated with each cursor, and the returned value should be a (not necessarily proper) sublist of the result states of this cursor. (This list can be retrieved by calling MergeCursor.getCursorStates().) To indicate that this cursor is done returning elements, this function should return the empty list.

Specified by:

computeNextResultStates in class MergeCursor<T,T,MergeCursorState<T>>

Returns:

the list of cursors to include in the next iteration

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

getContinuationObject

@Nonnull
protected com.apple.foundationdb.record.provider.foundationdb.cursors.UnionCursorContinuation getContinuationObject()

Description copied from class: MergeCursor

Produce a RecordCursorContinuation for this cursor. The super-class itself handles constructing the byte array continuation from this continuation. Most continuations will be based on the continuations of this cursors child cursors. These can be retrieved by calling MergeCursor.getChildContinuations(). This will only be called after MergeCursor.computeNextResultStates() has completed.

Specified by:

getContinuationObject in class MergeCursor<T,T,S extends MergeCursorState<T>>

Returns:

a RecordCursorContinuation for this cursor based on the state of its child cursors

getNextResult

@Nonnull
protected T getNextResult(@Nonnull
                          List<S> chosenStates)

Get the result from the list of chosen states. These states have all been identified as equivalent from the point of view of the union, so only one element should be returned from all of them. Implementations may choose to combine the results from the various child results if that is useful.

Specified by:

getNextResult in class MergeCursor<T,T,S extends MergeCursorState<T>>

Parameters:

chosenStates - the states that contain the next value to return

Returns:

the result to return from this cursor given these elements appear in the union

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.

Specified by:

mergeNoNextReasons in class MergeCursor<T,T,S extends MergeCursorState<T>>

Returns:

the strongest reason for stopping