Package com.apple.foundationdb.record.cursors

Class CursorLimitManager

java.lang.Object

com.apple.foundationdb.record.cursors.CursorLimitManager

@API(UNSTABLE)
public class CursorLimitManager
extends Object

Handles the logic of tracking various out-of-band limits on a BaseCursor. In contrast to the individual cursors, which may react to out-of-band limits in various ways (including ignoring them entirely), the limit manager merely tracks the limit state and provides a coherent answer to the questions: 1) Can the cursor advance without exceeding the limit? 2) What limit has been exceeded? This class also tracks whether or not the base cursor has produced any records. Except when reaching a limit throws an exception, a base cursor is always permitted to load at least one record before it is stopped by an out-of-band limit. This contract ensures that cursors with multiple child cursors (such as UnionCursor and IntersectionCursor) can always make progress. This "free initial pass" is provided per cursor, not per limit: all out-band-limits share the same initial pass.

Constructor Summary

Constructors

Constructor	Description
CursorLimitManager(FDBRecordContext context, ScanProperties scanProperties)
CursorLimitManager(RecordScanLimiter recordScanLimiter, boolean failOnScanLimitReached, ByteScanLimiter byteScanLimiter, TimeScanLimiter timeScanLimiter)
CursorLimitManager(ScanProperties scanProperties)

Method Summary

Modifier and Type	Method	Description
Optional<RecordCursor.NoNextReason>	getStoppedReason()	Report a single reason associated with a limit that has been exceeded.
boolean	isStopped()	Report whether any limit handled by this manager has been exceeded.
void	reportScannedBytes(long byteSize)	Record that the specified number of bytes have been scanned and update the relevant limiters with this information.
boolean	tryRecordScan()	Inform the limit manager that a cursor is trying to scan a record.

Methods inherited from class java.lang.Object

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

Constructor Detail

CursorLimitManager

public CursorLimitManager(@Nullable
                          RecordScanLimiter recordScanLimiter,
                          boolean failOnScanLimitReached,
                          @Nullable
                          ByteScanLimiter byteScanLimiter,
                          @Nullable
                          TimeScanLimiter timeScanLimiter)

CursorLimitManager

public CursorLimitManager(@Nonnull
                          ScanProperties scanProperties)

CursorLimitManager

public CursorLimitManager(@Nullable
                          FDBRecordContext context,
                          @Nonnull
                          ScanProperties scanProperties)

Method Detail

isStopped

public boolean isStopped()

Report whether any limit handled by this manager has been exceeded.

Returns:

true if any limit has been exceeded and false otherwise

getStoppedReason

public Optional<RecordCursor.NoNextReason> getStoppedReason()

Report a single reason associated with a limit that has been exceeded. If more than one limit has been exceeded, return the more important one. If no limit has been exceeded, return Optional.emtpy().

Returns:

a reason for a limit that has been exceeded or Optional.empty() if no limit has been exceeded

tryRecordScan

public boolean tryRecordScan()

Inform the limit manager that a cursor is trying to scan a record. If no limit would be exceeded after scanning another record, return true and update the internal state to reflect that record scan. If a limit would be exceeded by scanning another record, return false and update the state accordingly.

Returns:

true if another record scan would not exceed any limit and false if it would

Throws:

ScanLimitReachedException - if the scan limit was reached and ExecuteProperties.isFailOnScanLimitReached()

reportScannedBytes

public void reportScannedBytes(long byteSize)

Record that the specified number of bytes have been scanned and update the relevant limiters with this information.

Parameters:

byteSize - the number of bytes scanned