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.

const (

    // TestSklPageSize is passed to tests as the size of each page in the
    // sklImpl to limit its memory footprint. Reducing this size can hurt
    // performance but it decreases the risk of OOM failures when many tests
    // are running concurrently.
    TestSklPageSize = 128 << 10 // 128 KB

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. readCache specifies whether the command
    // adding this timestamp should update the read timestamp; false to update
    // the write timestamp cache.
    Add(start, end roachpb.Key, ts hlc.Timestamp, txnID uuid.UUID, readCache bool)
    // 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)

    // GetMaxRead returns the maximum read 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.
    GetMaxRead(start, end roachpb.Key) (hlc.Timestamp, uuid.UUID)
    // GetMaxWrite behaves like GetMaxRead, but returns the maximum write
    // timestamp which overlaps the interval spanning from start to end.
    GetMaxWrite(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, pageSize uint32) Cache

New returns a new timestamp cache with the supplied hybrid clock. If the pageSize is provided, it will override the default page size.

type Metrics Uses

type Metrics struct {
    Skl sklImplMetrics

Metrics holds all metrics relating to a Cache.

Package tscache imports 19 packages (graph) and is imported by 5 packages. Updated 2019-07-09. Refresh now. Tools for package owners.