cockroach: Index | Files

package tscache

import ""

Package tscache provides a timestamp cache structure that records the maximum timestamp that key ranges were read from and written to.


Package Files

cache.go interval_skl.go metrics.go skl_impl.go tree_impl.go


const MinRetentionWindow = 10 * time.Second

MinRetentionWindow specifies the minimum duration to hold entries in the cache before allowing eviction. After this window expires, transactions writing to this node with timestamps lagging by more than MinRetentionWindow will necessarily have to advance their commit timestamp.

type Cache Uses

type Cache interface {
    // Add adds the specified timestamp to the cache covering the range of keys
    // from start to end. If end is nil, the range covers the start key only.
    // txnID is nil for no transaction.
    Add(start, end roachpb.Key, ts hlc.Timestamp, txnID uuid.UUID)
    // SetLowWater sets the low water mark of the cache for the specified span
    // to the provided timestamp.
    SetLowWater(start, end roachpb.Key, ts hlc.Timestamp)

    // GetMax returns the maximum timestamp which overlaps the interval spanning
    // from start to end. If that maximum timestamp belongs to a single
    // transaction, that transaction's ID is returned. Otherwise, if that maximum
    // is shared between multiple transactions, no transaction ID is returned.
    // Finally, if no part of the specified range is overlapped by timestamp
    // intervals from any transactions in the cache, the low water timestamp is
    // returned for the read timestamps.
    GetMax(start, end roachpb.Key) (hlc.Timestamp, uuid.UUID)

    // Metrics returns the Cache's metrics struct.
    Metrics() Metrics
    // contains filtered or unexported methods

Cache is a bounded in-memory cache that records the maximum timestamp that key ranges were read from and written to. The structure serves to protect against violations of Snapshot Isolation, which requires that the outcome of reads must be preserved even in the presence of read-write conflicts (i.e. a write to a key at a lower timestamp than a previous read must not succeed). Cache corresponds to the "status oracle" discussed in Yabandeh's A Critique of Snapshot Isolation.

The cache is updated after the completion of each read operation with the range of all keys that the request was predicated upon. It is then consulted for each write operation, allowing them to detect read-write violations that would allow them to write "under" a read that has already been performed.

The cache is size-limited, so to prevent read-write conflicts for arbitrarily old requests, it pessimistically maintains a “low water mark”. This value always ratchets with monotonic increases and is equivalent to the earliest timestamp of any key range that is present in the cache. If a write operation writes to a key not present in the cache, the “low water mark” is consulted instead to determine read-write conflicts. The low water mark is initialized to the current system time plus the maximum clock offset.

All Cache implementations are safe for concurrent use by multiple goroutines.

func New Uses

func New(clock *hlc.Clock) Cache

New returns a new timestamp cache with the supplied hybrid-logical clock.

type Metrics Uses

type Metrics struct {
    Skl sklMetrics

Metrics holds all metrics relating to a Cache.

Package tscache imports 20 packages (graph) and is imported by 2 packages. Updated 2020-08-12. Refresh now. Tools for package owners.