Support adaptive update interval for low resolution ts

oracle/oracle.go

@@ -51,6 +51,12 @@ type Oracle interface {
 	GetLowResolutionTimestamp(ctx context.Context, opt *Option) (uint64, error)
 	GetLowResolutionTimestampAsync(ctx context.Context, opt *Option) Future
 	SetLowResolutionTimestampUpdateInterval(time.Duration) error
+	// GetStaleTimestamp generates a timestamp based on the recently fetched timestamp and the elapsed time since
+	// when that timestamp was fetched. The result is expected to be about `prevSecond` seconds before the current
+	// time.
+	// WARNING: This method does not guarantee whether the generated timestamp is legal for accessing the data.
+	// Neither is it safe to use it for verifying the legality of another calculated timestamp.
+	// Be sure to validate the timestamp before using it to access the data.
 	GetStaleTimestamp(ctx context.Context, txnScope string, prevSecond uint64) (uint64, error)
 	IsExpired(lockTimestamp, TTL uint64, opt *Option) bool
 	UntilExpired(lockTimeStamp, TTL uint64, opt *Option) int64
@@ -61,6 +67,13 @@ type Oracle interface {
 
 	// GetAllTSOKeyspaceGroupMinTS gets a minimum timestamp from all TSO keyspace groups.
 	GetAllTSOKeyspaceGroupMinTS(ctx context.Context) (uint64, error)
+
+	// ValidateSnapshotReadTS verifies whether it can be guaranteed that the given readTS doesn't exceed the maximum ts
+	// that has been allocated by the oracle, so that it's safe to use this ts to perform snapshot read, stale read,
+	// etc.
+	// Note that this method only checks the ts from the oracle's perspective. It doesn't check whether the snapshot
+	// has been GCed.
+	ValidateSnapshotReadTS(ctx context.Context, readTS uint64, opt *Option) error
 }
 
 // Future is a future which promises to return a timestamp.

oracle/oracles/local.go

@@ -39,6 +39,7 @@ import (
 	"sync"
 	"time"
 
+	"github.com/pingcap/errors"
 	"github.com/tikv/client-go/v2/oracle"
 )
 
@@ -148,3 +149,14 @@ func (l *localOracle) SetExternalTimestamp(ctx context.Context, newTimestamp uin
 func (l *localOracle) GetExternalTimestamp(ctx context.Context) (uint64, error) {
 	return l.getExternalTimestamp(ctx)
 }
+
+func (l *localOracle) ValidateSnapshotReadTS(ctx context.Context, readTS uint64, opt *oracle.Option) error {
+	currentTS, err := l.GetTimestamp(ctx, opt)
+	if err != nil {
+		return errors.Errorf("fail to validate read timestamp: %v", err)
+	}
+	if currentTS < readTS {
+		return errors.Errorf("cannot set read timestamp to a future time")
+	}
+	return nil
+}

oracle/oracles/mock.go

@@ -137,6 +137,17 @@ func (o *MockOracle) SetLowResolutionTimestampUpdateInterval(time.Duration) erro
 	return nil
 }
 
+func (o *MockOracle) ValidateSnapshotReadTS(ctx context.Context, readTS uint64, opt *oracle.Option) error {
+	currentTS, err := o.GetTimestamp(ctx, opt)
+	if err != nil {
+		return errors.Errorf("fail to validate read timestamp: %v", err)
+	}
+	if currentTS < readTS {
+		return errors.Errorf("cannot set read timestamp to a future time")
+	}
+	return nil
+}
+
 // IsExpired implements oracle.Oracle interface.
 func (o *MockOracle) IsExpired(lockTimestamp, TTL uint64, _ *oracle.Option) bool {
 	o.RLock()