cockroach: Index | Files

package kvcoord

import ""

Package kvcoord provides a key-value API to an underlying cockroach datastore. Cockroach itself provides a single, monolithic, sorted key value map, distributed over multiple nodes. Each node holds a set of key ranges. Package kv translates between the monolithic, logical map which Cockroach clients experience to the physically distributed key ranges which comprise the whole.

Package kv implements the logic necessary to locate appropriate nodes based on keys being read or written. In some cases, requests may span a range of keys, in which case multiple RPCs may be sent out.


Package Files

batch.go condensable_span_set.go dist_sender.go dist_sender_rangefeed.go doc.go local_test_cluster_util.go node_store.go range_cache.go range_iter.go replica_slice.go testing_knobs.go transport.go transport_regular.go txn_coord_sender.go txn_coord_sender_factory.go txn_coord_sender_savepoints.go txn_interceptor_committer.go txn_interceptor_heartbeater.go txn_interceptor_metric_recorder.go txn_interceptor_pipeliner.go txn_interceptor_seq_num_allocator.go txn_interceptor_span_refresher.go txn_lock_gatekeeper.go txn_metrics.go txnstate_string.go


const (
    // OpTxnCoordSender represents a txn coordinator send operation.
    OpTxnCoordSender = "txn coordinator send"


var CanSendToFollower = func(
    clusterID uuid.UUID, st *cluster.Settings, ba roachpb.BatchRequest,
) bool {
    return false

CanSendToFollower is used by the DistSender to determine if it needs to look up the current lease holder for a request. It is used by the followerreadsccl code to inject logic to check if follower reads are enabled. By default, without CCL code, this function returns false.

var ErrSavepointOperationInErrorTxn error = errSavepointOperationInErrorTxn{}

ErrSavepointOperationInErrorTxn is reported when CreateSavepoint() or ReleaseSavepoint() is called over a txn currently in error.

var MaxTxnRefreshSpansBytes = settings.RegisterPublicIntSetting(
    "maximum number of bytes used to track refresh spans in serializable transactions",

MaxTxnRefreshSpansBytes is a threshold in bytes for refresh spans stored on the coordinator during the lifetime of a transaction. Refresh spans are used for SERIALIZABLE transactions to avoid client restarts.

func InitFactoryForLocalTestCluster Uses

func InitFactoryForLocalTestCluster(
    st *cluster.Settings,
    nodeDesc *roachpb.NodeDescriptor,
    tracer opentracing.Tracer,
    clock *hlc.Clock,
    latency time.Duration,
    stores kv.Sender,
    stopper *stop.Stopper,
    gossip *gossip.Gossip,
) kv.TxnSenderFactory

InitFactoryForLocalTestCluster initializes a TxnCoordSenderFactory that can be used with LocalTestCluster.

type ClientTestingKnobs Uses

type ClientTestingKnobs struct {
    // The RPC dispatcher. Defaults to grpc but can be changed here for
    // testing purposes.
    TransportFactory TransportFactory

    // The maximum number of times a txn will attempt to refresh its
    // spans for a single transactional batch.
    // 0 means use a default. -1 means disable refresh.
    MaxTxnRefreshAttempts int

    // CondenseRefreshSpansFilter, if set, is called when the span refresher is
    // considering condensing the refresh spans. If it returns false, condensing
    // will not be attempted and the span refresher will behave as if condensing
    // failed to save enough memory.
    CondenseRefreshSpansFilter func() bool

    // LatencyFunc, if set, overrides RPCContext.RemoteClocks.Latency as the
    // function used by the DistSender to order replicas for follower reads.
    LatencyFunc LatencyFunc

ClientTestingKnobs contains testing options that dictate the behavior of the key-value client.

func (*ClientTestingKnobs) ModuleTestingKnobs Uses

func (*ClientTestingKnobs) ModuleTestingKnobs()

ModuleTestingKnobs is part of the base.ModuleTestingKnobs interface.

type DistSender Uses

type DistSender struct {
    // contains filtered or unexported fields

A DistSender provides methods to access Cockroach's monolithic, distributed key value store. Each method invocation triggers a lookup or lookups to find replica metadata for implicated key ranges. RPCs are sent to one or more of the replicas to satisfy the method invocation.

func NewDistSender Uses

func NewDistSender(cfg DistSenderConfig) *DistSender

NewDistSender returns a batch.Sender instance which connects to the Cockroach cluster via the supplied gossip instance. Supplying a DistSenderContext or the fields within is optional. For omitted values, sane defaults will be used.

func NewDistSenderForLocalTestCluster Uses

func NewDistSenderForLocalTestCluster(
    st *cluster.Settings,
    nodeDesc *roachpb.NodeDescriptor,
    tracer opentracing.Tracer,
    clock *hlc.Clock,
    latency time.Duration,
    stores kv.Sender,
    stopper *stop.Stopper,
    g *gossip.Gossip,
) *DistSender

NewDistSenderForLocalTestCluster creates a DistSender for a LocalTestCluster.

func (*DistSender) CountRanges Uses

func (ds *DistSender) CountRanges(ctx context.Context, rs roachpb.RSpan) (int64, error)

CountRanges returns the number of ranges that encompass the given key span.

func (*DistSender) DisableFirstRangeUpdates Uses

func (ds *DistSender) DisableFirstRangeUpdates()

DisableFirstRangeUpdates disables updates of the first range via gossip. Used by tests which want finer control of the contents of the range cache.

func (*DistSender) DisableParallelBatches Uses

func (ds *DistSender) DisableParallelBatches()

DisableParallelBatches instructs DistSender to never parallelize the transmission of partial batch requests across ranges.

func (*DistSender) FirstRange Uses

func (ds *DistSender) FirstRange() (*roachpb.RangeDescriptor, error)

FirstRange implements the RangeDescriptorDB interface.

It returns the RangeDescriptor for the first range in the cluster using the FirstRangeProvider, which is typically implemented using the gossip protocol instead of the datastore.

func (*DistSender) Metrics Uses

func (ds *DistSender) Metrics() DistSenderMetrics

Metrics returns a struct which contains metrics related to the distributed sender's activity.

func (*DistSender) RangeDescriptorCache Uses

func (ds *DistSender) RangeDescriptorCache() *RangeDescriptorCache

RangeDescriptorCache gives access to the DistSender's range cache.

func (*DistSender) RangeFeed Uses

func (ds *DistSender) RangeFeed(
    ctx context.Context,
    span roachpb.Span,
    ts hlc.Timestamp,
    withDiff bool,
    eventCh chan<- *roachpb.RangeFeedEvent,
) error

RangeFeed divides a RangeFeed request on range boundaries and establishes a RangeFeed to each of the individual ranges. It streams back results on the provided channel.

Note that the timestamps in RangeFeedCheckpoint events that are streamed back may be lower than the timestamp given here.

func (*DistSender) RangeLookup Uses

func (ds *DistSender) RangeLookup(
    ctx context.Context, key roachpb.RKey, useReverseScan bool,
) ([]roachpb.RangeDescriptor, []roachpb.RangeDescriptor, error)

RangeLookup implements the RangeDescriptorDB interface.

It uses LookupRange to perform a lookup scan for the provided key, using DistSender itself as the client.Sender. This means that the scan will recurse into DistSender, which will in turn use the RangeDescriptorCache again to lookup the RangeDescriptor necessary to perform the scan.

func (*DistSender) Send Uses

func (ds *DistSender) Send(
    ctx context.Context, ba roachpb.BatchRequest,
) (*roachpb.BatchResponse, *roachpb.Error)

Send implements the batch.Sender interface. It subdivides the Batch into batches admissible for sending (preventing certain illegal mixtures of requests), executes each individual part (which may span multiple ranges), and recombines the response.

When the request spans ranges, it is split by range and a partial subset of the batch request is sent to affected ranges in parallel.

type DistSenderConfig Uses

type DistSenderConfig struct {
    AmbientCtx log.AmbientContext

    Settings  *cluster.Settings
    Clock     *hlc.Clock
    NodeDescs NodeDescStore

    RPCRetryOptions *retry.Options
    RPCContext      *rpc.Context
    NodeDialer      *nodedialer.Dialer

    // One of the following two must be provided, but not both.
    // If only FirstRangeProvider is supplied, DistSender will use itself as a
    // RangeDescriptorDB and scan the meta ranges directly to satisfy range
    // lookups, using the FirstRangeProvider to bootstrap the location of the
    // meta1 range. Additionally, it will proactively update its range
    // descriptor cache with any meta1 updates from the provider.
    // If only RangeDescriptorDB is provided, all range lookups will be
    // delegated to it.
    // If both are provided (not required, but allowed for tests) range lookups
    // will be delegated to the RangeDescriptorDB but FirstRangeProvider will
    // still be used to listen for updates to the first range's descriptor.
    FirstRangeProvider FirstRangeProvider
    RangeDescriptorDB  RangeDescriptorDB

    TestingKnobs ClientTestingKnobs
    // contains filtered or unexported fields

DistSenderConfig holds configuration and auxiliary objects that can be passed to NewDistSender.

type DistSenderMetrics Uses

type DistSenderMetrics struct {
    BatchCount              *metric.Counter
    PartialBatchCount       *metric.Counter
    AsyncSentCount          *metric.Counter
    AsyncThrottledCount     *metric.Counter
    SentCount               *metric.Counter
    LocalSentCount          *metric.Counter
    NextReplicaErrCount     *metric.Counter
    NotLeaseHolderErrCount  *metric.Counter
    InLeaseTransferBackoffs *metric.Counter
    RangeLookups            *metric.Counter
    SlowRPCs                *metric.Gauge
    MethodCounts            [roachpb.NumMethods]*metric.Counter

DistSenderMetrics is the set of metrics for a given distributed sender.

type EvictionToken Uses

type EvictionToken struct {
    // contains filtered or unexported fields

EvictionToken holds eviction state between calls to Lookup.

func (EvictionToken) ClearLease Uses

func (et EvictionToken) ClearLease(ctx context.Context) EvictionToken

ClearLease evicts information about the current lease from the cache, if the cache entry referenced by the token is still in the cache.

Similarly to UpdateLease(), ClearLease() acts as a synchronization point between the caller and the RangeDescriptorCache. The caller might get an updated token (besides the lease).

Returns the updated EvictionToken. Note that this updated token might have a newer descriptor than before and/or still have a lease in it - in case the cache already had a more recent entry. The returned descriptor is compatible (same range id and key span) to the original one. Returns an empty token if the cache has a more recent entry, but the current descriptor is incompatible. Callers should interpret such a response as a signal that they should use a range iterator again to get updated ranges.

func (EvictionToken) Desc Uses

func (et EvictionToken) Desc() *roachpb.RangeDescriptor

Desc returns the RangeDescriptor that was retrieved from the cache. The result is to be considered immutable.

Note that the returned descriptor might have Generation = 0. This means that the descriptor is speculative; it is not know to have committed.

func (EvictionToken) Empty Uses

func (et EvictionToken) Empty() bool

Empty returns true if the token is not populated.

func (EvictionToken) Evict Uses

func (et EvictionToken) Evict(ctx context.Context)

Evict instructs the EvictionToken to evict the RangeDescriptor it was created with from the RangeDescriptorCache.

func (EvictionToken) EvictAndReplace Uses

func (et EvictionToken) EvictAndReplace(ctx context.Context, newDescs ...roachpb.RangeInfo)

EvictAndReplace instructs the EvictionToken to evict the RangeDescriptor it was created with from the RangeDescriptorCache. It also allows the user to provide new RangeDescriptors to insert into the cache, all atomically. When called without arguments, EvictAndReplace will behave the same as Evict.

func (EvictionToken) LeaseSeq Uses

func (et EvictionToken) LeaseSeq() roachpb.LeaseSequence

LeaseSeq returns the sequence of the cached lease. If no lease is cached, or the cached lease is speculative, 0 is returned.

func (EvictionToken) Leaseholder Uses

func (et EvictionToken) Leaseholder() *roachpb.ReplicaDescriptor

Leaseholder returns the cached leaseholder. If the cache didn't have any lease information, returns nil. The result is to be considered immutable.

If a leaseholder is returned, it will correspond to one of the replicas in et.Desc().

func (EvictionToken) UpdateLease Uses

func (et EvictionToken) UpdateLease(
    ctx context.Context, lease *roachpb.Lease,
) (EvictionToken, bool)

UpdateLease updates the leaseholder for the token's cache entry to the specified lease, and returns an updated EvictionToken, tied to the new cache entry.

The bool retval is true if the requested update was performed (i.e. the passed-in lease was compatible with the descriptor and more recent than the cached lease).

UpdateLease also acts as a synchronization point between the caller and the RangeDescriptorCache. In the spirit of a Compare-And-Swap operation (but unfortunately not quite as simple), it returns updated information (besides the lease) from the cache in case the EvictionToken was no longer up to date with the cache entry from whence it came.

The updated token might have a newer descriptor than before and/or a newer lease than the one passed-in - in case the cache already had a more recent entry. The returned entry has a descriptor compatible to the original one (same range id and key span).

If the passed-in lease is incompatible with the cached descriptor (i.e. the leaseholder is not a replica in the cached descriptor), then the existing entry is evicted and an empty token is returned. The caller should take an empty returned token to mean that the information it was working with is too stale to be useful, and it should use a range iterator again to get an updated cache entry.

It's legal to pass in a lease with a zero Sequence; it will be treated as a speculative lease and considered newer than any existing lease (and then in turn will be overridden by any subsequent update).

func (EvictionToken) UpdateLeaseholder Uses

func (et EvictionToken) UpdateLeaseholder(
    ctx context.Context, lh roachpb.ReplicaDescriptor,
) EvictionToken

UpdateLeaseholder is like UpdateLease(), but it only takes a leaseholder, not a full lease. This is called when a likely leaseholder is known, but not a full lease. The lease we'll insert into the cache will be considered "speculative".

type FirstRangeProvider Uses

type FirstRangeProvider interface {
    // GetFirstRangeDescriptor returns the RangeDescriptor for the first range
    // in the cluster.
    GetFirstRangeDescriptor() (*roachpb.RangeDescriptor, error)

    // OnFirstRangeChanged calls the provided callback when the RangeDescriptor
    // for the first range has changed.

FirstRangeProvider is capable of providing DistSender with the descriptor of the first range in the cluster and notifying the DistSender when the first range in the cluster has changed.

type LatencyFunc Uses

type LatencyFunc func(string) (time.Duration, bool)

A LatencyFunc returns the latency from this node to a remote address and a bool indicating whether the latency is valid.

type NodeDescStore Uses

type NodeDescStore interface {
    // GetNodeDescriptor looks up the descriptor of the node by ID.
    // It returns an error if the node is not known by the store.
    GetNodeDescriptor(roachpb.NodeID) (*roachpb.NodeDescriptor, error)

NodeDescStore stores a collection of NodeDescriptors.

Implementations of the interface are expected to be threadsafe.

type RangeDescriptorCache Uses

type RangeDescriptorCache struct {
    // contains filtered or unexported fields

RangeDescriptorCache is used to retrieve range descriptors for arbitrary keys. Descriptors are initially queried from storage using a RangeDescriptorDB, but are cached for subsequent lookups.

func NewRangeDescriptorCache Uses

func NewRangeDescriptorCache(
    st *cluster.Settings, db RangeDescriptorDB, size func() int64, stopper *stop.Stopper,
) *RangeDescriptorCache

NewRangeDescriptorCache returns a new RangeDescriptorCache which uses the given RangeDescriptorDB as the underlying source of range descriptors.

func (*RangeDescriptorCache) Clear Uses

func (rdc *RangeDescriptorCache) Clear()

Clear clears all RangeDescriptors from the RangeDescriptorCache.

func (*RangeDescriptorCache) EvictByKey Uses

func (rdc *RangeDescriptorCache) EvictByKey(ctx context.Context, descKey roachpb.RKey) bool

EvictByKey evicts the descriptor containing the given key, if any.

Returns true if a descriptor was evicted.

func (*RangeDescriptorCache) GetCached Uses

func (rdc *RangeDescriptorCache) GetCached(key roachpb.RKey, inverted bool) kvbase.RangeCacheEntry

GetCached retrieves the descriptor of the range which contains the given key. It returns nil if the descriptor is not found in the cache.

`inverted` determines the behavior at the range boundary: If set to true and `key` is the EndKey and StartKey of two adjacent ranges, the first range is returned instead of the second (which technically contains the given key).

func (*RangeDescriptorCache) GetCachedOverlapping Uses

func (rdc *RangeDescriptorCache) GetCachedOverlapping(
    ctx context.Context, span roachpb.RSpan,
) []kvbase.RangeCacheEntry

GetCachedOverlapping returns all the cached entries which overlap a given span.

func (*RangeDescriptorCache) Insert Uses

func (rdc *RangeDescriptorCache) Insert(ctx context.Context, rs ...roachpb.RangeInfo)

Insert inserts range info into the cache.

This is a no-op for the ranges that already have the same, or newer, info in the cache.

func (*RangeDescriptorCache) Lookup Uses

func (rdc *RangeDescriptorCache) Lookup(
    ctx context.Context, key roachpb.RKey,
) (kvbase.RangeCacheEntry, error)

Lookup presents a simpler interface for looking up a RangeDescriptor for a key without the eviction tokens or scan direction control of LookupWithEvictionToken. This method is exported to lower level clients through the kvbase.RangeDescriptorCache interface.

func (*RangeDescriptorCache) LookupWithEvictionToken Uses

func (rdc *RangeDescriptorCache) LookupWithEvictionToken(
    ctx context.Context, key roachpb.RKey, evictToken EvictionToken, useReverseScan bool,
) (EvictionToken, error)

LookupWithEvictionToken attempts to locate a descriptor, and possibly also a lease) for the range containing the given key. This is done by first trying the cache, and then querying the two-level lookup table of range descriptors which cockroach maintains. The function should be provided with an EvictionToken if one was acquired from this function on a previous lookup. If not, a nil EvictionToken can be provided.

This method first looks up the specified key in the first level of range metadata, which returns the location of the key within the second level of range metadata. This second level location is then queried to retrieve a descriptor for the range where the key's value resides. Range descriptors retrieved during each search are cached for subsequent lookups.

The returned EvictionToken contains the descriptor and, possibly, the lease. It can also be used to evict information from the cache if it's found to be stale.

func (*RangeDescriptorCache) String Uses

func (rdc *RangeDescriptorCache) String() string

type RangeDescriptorDB Uses

type RangeDescriptorDB interface {
    // RangeLookup takes a key to look up descriptors for. Two slices of range
    // descriptors are returned. The first of these slices holds descriptors
    // whose [startKey,endKey) spans contain the given key (possibly from
    // intents), and the second holds prefetched adjacent descriptors.
        ctx context.Context, key roachpb.RKey, useReverseScan bool,
    ) ([]roachpb.RangeDescriptor, []roachpb.RangeDescriptor, error)

    // FirstRange returns the descriptor for the first Range. This is the
    // Range containing all meta1 entries.
    // TODO(nvanbenschoten): pull this detail in DistSender.
    FirstRange() (*roachpb.RangeDescriptor, error)

RangeDescriptorDB is a type which can query range descriptors from an underlying datastore. This interface is used by RangeDescriptorCache to initially retrieve information which will be cached.

type RangeIterator Uses

type RangeIterator struct {
    // contains filtered or unexported fields

A RangeIterator provides a mechanism for iterating over all ranges in a key span. A new RangeIterator must be positioned with Seek() to begin iteration.

RangeIterator is not thread-safe.

func NewRangeIterator Uses

func NewRangeIterator(ds *DistSender) *RangeIterator

NewRangeIterator creates a new RangeIterator.

func (*RangeIterator) Desc Uses

func (ri *RangeIterator) Desc() *roachpb.RangeDescriptor

Desc returns the descriptor of the range at which the iterator is currently positioned. The iterator must be valid.

The returned descriptor is immutable.

func (*RangeIterator) Error Uses

func (ri *RangeIterator) Error() error

Error returns the error the iterator encountered, if any. If the iterator has not been initialized, returns iterator error.

func (*RangeIterator) Key Uses

func (ri *RangeIterator) Key() roachpb.RKey

Key returns the current key. The iterator must be valid.

func (*RangeIterator) Leaseholder Uses

func (ri *RangeIterator) Leaseholder() *roachpb.ReplicaDescriptor

Leaseholder returns information about the leaseholder of the range at which the iterator is currently positioned. The iterator must be valid.

The lease information comes from a cache, and so it can be stale. Returns nil if no lease information is known.

The returned lease is immutable.

func (*RangeIterator) NeedAnother Uses

func (ri *RangeIterator) NeedAnother(rs roachpb.RSpan) bool

NeedAnother checks whether the iteration needs to continue to cover the remainder of the ranges described by the supplied key span. The iterator must be valid.

func (*RangeIterator) Next Uses

func (ri *RangeIterator) Next(ctx context.Context)

Next advances the iterator to the next range. The direction of advance is dependent on whether the iterator is reversed. The iterator must be valid.

func (*RangeIterator) Reset Uses

func (ri *RangeIterator) Reset()

Reset resets the RangeIterator to its initial state.

func (*RangeIterator) Seek Uses

func (ri *RangeIterator) Seek(ctx context.Context, key roachpb.RKey, scanDir ScanDirection)

Seek positions the iterator at the specified key.

func (*RangeIterator) Token Uses

func (ri *RangeIterator) Token() EvictionToken

Token returns the eviction token corresponding to the range descriptor for the current iteration. The iterator must be valid.

func (*RangeIterator) Valid Uses

func (ri *RangeIterator) Valid() bool

Valid returns whether the iterator is valid. To be valid, the iterator must be have been seeked to an initial position using Seek(), and must not have encountered an error.

type ReplicaInfo Uses

type ReplicaInfo struct {
    NodeDesc *roachpb.NodeDescriptor

ReplicaInfo extends the Replica structure with the associated node descriptor.

type ReplicaSlice Uses

type ReplicaSlice []ReplicaInfo

A ReplicaSlice is a slice of ReplicaInfo.

func NewReplicaSlice Uses

func NewReplicaSlice(
    ctx context.Context,
    nodeDescs NodeDescStore,
    desc *roachpb.RangeDescriptor,
    leaseholder *roachpb.ReplicaDescriptor,
) (ReplicaSlice, error)

NewReplicaSlice creates a ReplicaSlice from the replicas listed in the range descriptor and using gossip to lookup node descriptors. Replicas on nodes that are not gossiped are omitted from the result.

Generally, only voting replicas are returned. However, if a non-nil leaseholder is passed in, it will be included in the result even if the descriptor has it as a learner (we assert that the leaseholder is part of the descriptor). The idea is that the descriptor might be stale and list the leaseholder as a learner erroneously, and lease info is a strong signal in that direction. Note that the returned ReplicaSlice might still not include the leaseholder if info for the respective node is missing from the NodeDescStore.

If there's no info in gossip for any of the nodes in the descriptor, a sendError is returned.

func (ReplicaSlice) Find Uses

func (rs ReplicaSlice) Find(id roachpb.ReplicaID) int

Find returns the index of the specified ReplicaID, or -1 if missing.

func (ReplicaSlice) Len Uses

func (rs ReplicaSlice) Len() int

Len returns the total number of replicas in the slice.

func (ReplicaSlice) MoveToFront Uses

func (rs ReplicaSlice) MoveToFront(i int)

MoveToFront moves the replica at the given index to the front of the slice, keeping the order of the remaining elements stable. The function will panic when invoked with an invalid index.

func (ReplicaSlice) OptimizeReplicaOrder Uses

func (rs ReplicaSlice) OptimizeReplicaOrder(
    nodeDesc *roachpb.NodeDescriptor, latencyFn LatencyFunc,

OptimizeReplicaOrder sorts the replicas in the order in which they're to be used for sending RPCs (meaning in the order in which they'll be probed for the lease). Lower latency and "closer" (matching in more attributes) replicas are ordered first. If the current node is a replica, then it'll be the first one.

nodeDesc is the descriptor of the current node. It can be nil, in which case information about the current descriptor is not used in optimizing the order.

Note that this method is not concerned with any information the node might have about who the lease holder might be. If the leaseholder is known by the caller, the caller will move it to the front if appropriate.

func (ReplicaSlice) Swap Uses

func (rs ReplicaSlice) Swap(i, j int)

Swap swaps the replicas with indexes i and j.

type ScanDirection Uses

type ScanDirection byte

ScanDirection determines the semantics of RangeIterator.Next() and RangeIterator.NeedAnother().

const (
    // Ascending means Next() will advance towards keys that compare higher.
    Ascending ScanDirection = iota
    // Descending means Next() will advance towards keys that compare lower.

type SendOptions Uses

type SendOptions struct {
    // contains filtered or unexported fields

A SendOptions structure describes the algorithm for sending RPCs to one or more replicas, depending on error conditions and how many successful responses are required.

type Transport Uses

type Transport interface {
    // IsExhausted returns true if there are no more replicas to try.
    IsExhausted() bool

    // SendNext synchronously sends the BatchRequest rpc to the next replica.
    // May panic if the transport is exhausted.
    // SendNext is also in charge of importing the remotely collected spans (if
    // any) into the local trace.
    SendNext(context.Context, roachpb.BatchRequest) (*roachpb.BatchResponse, error)

    // NextInternalClient returns the InternalClient to use for making RPC
    // calls. Returns a context.Context which should be used when making RPC
    // calls on the returned server (This context is annotated to mark this
    // request as in-process and bypass ctx.Peer checks).
    NextInternalClient(context.Context) (context.Context, roachpb.InternalClient, error)

    // NextReplica returns the replica descriptor of the replica to be tried in
    // the next call to SendNext. MoveToFront will cause the return value to
    // change. Returns a zero value if the transport is exhausted.
    NextReplica() roachpb.ReplicaDescriptor

    // SkipReplica changes the replica that the next SendNext() call would sent to
    // - the replica that NextReplica() would return is skipped.

    // MoveToFront locates the specified replica and moves it to the
    // front of the ordering of replicas to try. If the replica has
    // already been tried, it will be retried. If the specified replica
    // can't be found, this is a noop.

Transport objects can send RPCs to one or more replicas of a range. All calls to Transport methods are made from a single thread, so Transports are not required to be thread-safe.

func GRPCTransportFactory Uses

func GRPCTransportFactory(
    opts SendOptions, nodeDialer *nodedialer.Dialer, replicas ReplicaSlice,
) (Transport, error)

GRPCTransportFactory is the default TransportFactory, using GRPC.

type TransportFactory Uses

type TransportFactory func(
    SendOptions, *nodedialer.Dialer, ReplicaSlice,
) (Transport, error)

TransportFactory encapsulates all interaction with the RPC subsystem, allowing it to be mocked out for testing. The factory function returns a Transport object which is used to send requests to one or more replicas in the slice.

In addition to actually sending RPCs, the transport is responsible for ordering replicas in accordance with SendOptions.Ordering and transport-specific knowledge such as connection health or latency.

TODO(bdarnell): clean up this crufty interface; it was extracted verbatim from the non-abstracted code. TODO(andrei): This should take just []roachpb.ReplicaDescriptor; ReplicaSlice has unneeded data in it.

func SenderTransportFactory Uses

func SenderTransportFactory(tracer opentracing.Tracer, sender kv.Sender) TransportFactory

SenderTransportFactory wraps a client.Sender for use as a KV Transport. This is useful for tests that want to use DistSender without a full RPC stack.

type TxnCoordSender Uses

type TxnCoordSender struct {

    // A pointer member to the creating factory provides access to
    // immutable factory settings.
    // contains filtered or unexported fields

A TxnCoordSender is the production implementation of client.TxnSender. It is a Sender which wraps a lower-level Sender (a DistSender) to which it sends commands. It works on behalf of the client to keep a transaction's state (e.g. intents) and to perform periodic heartbeating of the transaction required when necessary. Unlike other senders, TxnCoordSender is not a singleton - an instance is created for every transaction by the TxnCoordSenderFactory.

Among the functions it performs are: - Heartbeating of the transaction record. Note that heartbeating is done only from the root transaction coordinator, in the event that multiple coordinators are active (i.e. in a distributed SQL flow). - Accumulating lock spans. - Attaching lock spans to EndTxn requests, for cleanup. - Handles retriable errors by either bumping the transaction's epoch or, in case of TransactionAbortedErrors, cleaning up the transaction (in this case, the client.Txn is expected to create a new TxnCoordSender instance transparently for the higher-level client).

Since it is stateful, the TxnCoordSender needs to understand when a transaction is "finished" and the state can be destroyed. As such there's a contract that the client.Txn needs obey. Read-only transactions don't matter - they're stateless. For the others, once an intent write is sent by the client, the TxnCoordSender considers the transactions completed in the following situations: - A batch containing an EndTxns (commit or rollback) succeeds. - A batch containing an EndTxn(commit=false) succeeds or fails. Only more rollback attempts can follow a rollback attempt. - A batch returns a TransactionAbortedError. As mentioned above, the client is expected to create a new TxnCoordSender for the next transaction attempt.

Note that "1PC" batches (i.e. batches containing both a Begin and an EndTxn) are no exception from the contract - if the batch fails, the client is expected to send a rollback (or perform another transaction attempt in case of retriable errors).

func (*TxnCoordSender) Active Uses

func (tc *TxnCoordSender) Active() bool

Active returns true if requests were sent already. Rolling back to a savepoint taken before any requests were sent resets this to false.

func (*TxnCoordSender) AnchorOnSystemConfigRange Uses

func (tc *TxnCoordSender) AnchorOnSystemConfigRange() error

AnchorOnSystemConfigRange is part of the client.TxnSender interface.

func (*TxnCoordSender) CommitTimestamp Uses

func (tc *TxnCoordSender) CommitTimestamp() hlc.Timestamp

CommitTimestamp is part of the client.TxnSender interface.

func (*TxnCoordSender) CommitTimestampFixed Uses

func (tc *TxnCoordSender) CommitTimestampFixed() bool

CommitTimestampFixed is part of the client.TxnSender interface.

func (*TxnCoordSender) ConfigureStepping Uses

func (tc *TxnCoordSender) ConfigureStepping(
    ctx context.Context, mode kv.SteppingMode,
) (prevMode kv.SteppingMode)

ConfigureStepping is part of the TxnSender interface.

func (*TxnCoordSender) CreateSavepoint Uses

func (tc *TxnCoordSender) CreateSavepoint(ctx context.Context) (kv.SavepointToken, error)

CreateSavepoint is part of the client.TxnSender interface.

func (*TxnCoordSender) DisablePipelining Uses

func (tc *TxnCoordSender) DisablePipelining() error

DisablePipelining is part of the client.TxnSender interface.

func (*TxnCoordSender) Epoch Uses

func (tc *TxnCoordSender) Epoch() enginepb.TxnEpoch

Epoch is part of the client.TxnSender interface.

func (*TxnCoordSender) GetLeafTxnFinalState Uses

func (tc *TxnCoordSender) GetLeafTxnFinalState(
    ctx context.Context, opt kv.TxnStatusOpt,
) (roachpb.LeafTxnFinalState, error)

GetLeafTxnFinalState is part of the client.TxnSender interface.

func (*TxnCoordSender) GetLeafTxnInputState Uses

func (tc *TxnCoordSender) GetLeafTxnInputState(
    ctx context.Context, opt kv.TxnStatusOpt,
) (roachpb.LeafTxnInputState, error)

GetLeafTxnInputState is part of the client.TxnSender interface.

func (*TxnCoordSender) GetSteppingMode Uses

func (tc *TxnCoordSender) GetSteppingMode(ctx context.Context) (curMode kv.SteppingMode)

GetSteppingMode is part of the TxnSender interface.

func (*TxnCoordSender) IsSerializablePushAndRefreshNotPossible Uses

func (tc *TxnCoordSender) IsSerializablePushAndRefreshNotPossible() bool

IsSerializablePushAndRefreshNotPossible is part of the client.TxnSender interface.

func (*TxnCoordSender) IsTracking Uses

func (tc *TxnCoordSender) IsTracking() bool

IsTracking returns true if the heartbeat loop is running.

func (*TxnCoordSender) ManualRestart Uses

func (tc *TxnCoordSender) ManualRestart(
    ctx context.Context, pri roachpb.UserPriority, ts hlc.Timestamp,

ManualRestart is part of the client.TxnSender interface.

func (*TxnCoordSender) PrepareRetryableError Uses

func (tc *TxnCoordSender) PrepareRetryableError(ctx context.Context, msg string) error

PrepareRetryableError is part of the client.TxnSender interface.

func (*TxnCoordSender) ProvisionalCommitTimestamp Uses

func (tc *TxnCoordSender) ProvisionalCommitTimestamp() hlc.Timestamp

ProvisionalCommitTimestamp is part of the client.TxnSender interface.

func (*TxnCoordSender) ReadTimestamp Uses

func (tc *TxnCoordSender) ReadTimestamp() hlc.Timestamp

ReadTimestamp is part of the client.TxnSender interface.

func (*TxnCoordSender) ReleaseSavepoint Uses

func (tc *TxnCoordSender) ReleaseSavepoint(ctx context.Context, s kv.SavepointToken) error

ReleaseSavepoint is part of the client.TxnSender interface.

func (*TxnCoordSender) RollbackToSavepoint Uses

func (tc *TxnCoordSender) RollbackToSavepoint(ctx context.Context, s kv.SavepointToken) error

RollbackToSavepoint is part of the client.TxnSender interface.

func (*TxnCoordSender) Send Uses

func (tc *TxnCoordSender) Send(
    ctx context.Context, ba roachpb.BatchRequest,
) (*roachpb.BatchResponse, *roachpb.Error)

Send is part of the client.TxnSender interface.

func (*TxnCoordSender) SetDebugName Uses

func (tc *TxnCoordSender) SetDebugName(name string)

SetDebugName is part of the client.TxnSender interface.

func (*TxnCoordSender) SetFixedTimestamp Uses

func (tc *TxnCoordSender) SetFixedTimestamp(ctx context.Context, ts hlc.Timestamp)

SetFixedTimestamp is part of the client.TxnSender interface.

func (*TxnCoordSender) SetUserPriority Uses

func (tc *TxnCoordSender) SetUserPriority(pri roachpb.UserPriority) error

SetUserPriority is part of the client.TxnSender interface.

func (*TxnCoordSender) Step Uses

func (tc *TxnCoordSender) Step(ctx context.Context) error

Step is part of the TxnSender interface.

func (*TxnCoordSender) String Uses

func (tc *TxnCoordSender) String() string

String is part of the client.TxnSender interface.

func (*TxnCoordSender) TestingCloneTxn Uses

func (tc *TxnCoordSender) TestingCloneTxn() *roachpb.Transaction

TestingCloneTxn is part of the client.TxnSender interface. This is for use by tests only. To derive leaf TxnCoordSenders, use GetLeafTxnInitialState instead.

func (*TxnCoordSender) TxnStatus Uses

func (tc *TxnCoordSender) TxnStatus() roachpb.TransactionStatus

TxnStatus is part of the client.TxnSender interface.

func (*TxnCoordSender) UpdateRootWithLeafFinalState Uses

func (tc *TxnCoordSender) UpdateRootWithLeafFinalState(
    ctx context.Context, tfs *roachpb.LeafTxnFinalState,

UpdateRootWithLeafFinalState is part of the client.TxnSender interface.

func (*TxnCoordSender) UpdateStateOnRemoteRetryableErr Uses

func (tc *TxnCoordSender) UpdateStateOnRemoteRetryableErr(
    ctx context.Context, pErr *roachpb.Error,
) *roachpb.Error

UpdateStateOnRemoteRetryableErr is part of the TxnSender interface.

type TxnCoordSenderFactory Uses

type TxnCoordSenderFactory struct {
    // contains filtered or unexported fields

TxnCoordSenderFactory implements client.TxnSenderFactory.

func NewTxnCoordSenderFactory Uses

func NewTxnCoordSenderFactory(
    cfg TxnCoordSenderFactoryConfig, wrapped kv.Sender,
) *TxnCoordSenderFactory

NewTxnCoordSenderFactory creates a new TxnCoordSenderFactory. The factory creates new instances of TxnCoordSenders.

func (*TxnCoordSenderFactory) LeafTransactionalSender Uses

func (tcf *TxnCoordSenderFactory) LeafTransactionalSender(
    tis *roachpb.LeafTxnInputState,
) kv.TxnSender

LeafTransactionalSender is part of the TxnSenderFactory interface.

func (*TxnCoordSenderFactory) Metrics Uses

func (tcf *TxnCoordSenderFactory) Metrics() TxnMetrics

Metrics returns the factory's metrics struct.

func (*TxnCoordSenderFactory) NonTransactionalSender Uses

func (tcf *TxnCoordSenderFactory) NonTransactionalSender() kv.Sender

NonTransactionalSender is part of the TxnSenderFactory interface.

func (*TxnCoordSenderFactory) RootTransactionalSender Uses

func (tcf *TxnCoordSenderFactory) RootTransactionalSender(
    txn *roachpb.Transaction, pri roachpb.UserPriority,
) kv.TxnSender

RootTransactionalSender is part of the TxnSenderFactory interface.

type TxnCoordSenderFactoryConfig Uses

type TxnCoordSenderFactoryConfig struct {
    AmbientCtx log.AmbientContext

    Settings *cluster.Settings
    Clock    *hlc.Clock
    Stopper  *stop.Stopper

    HeartbeatInterval time.Duration
    Linearizable      bool
    Metrics           TxnMetrics

    TestingKnobs ClientTestingKnobs

TxnCoordSenderFactoryConfig holds configuration and auxiliary objects that can be passed to NewTxnCoordSenderFactory.

type TxnMetrics Uses

type TxnMetrics struct {
    Aborts          *metric.Counter
    Commits         *metric.Counter
    Commits1PC      *metric.Counter // Commits which finished in a single phase
    ParallelCommits *metric.Counter // Commits which entered the STAGING state

    RefreshSuccess                *metric.Counter
    RefreshFail                   *metric.Counter
    RefreshFailWithCondensedSpans *metric.Counter
    RefreshMemoryLimitExceeded    *metric.Counter

    Durations *metric.Histogram

    // Restarts is the number of times we had to restart the transaction.
    Restarts *metric.Histogram

    // Counts of restart types.
    RestartsWriteTooOld           telemetry.CounterWithMetric
    RestartsWriteTooOldMulti      telemetry.CounterWithMetric
    RestartsSerializable          telemetry.CounterWithMetric
    RestartsAsyncWriteFailure     telemetry.CounterWithMetric
    RestartsReadWithinUncertainty telemetry.CounterWithMetric
    RestartsTxnAborted            telemetry.CounterWithMetric
    RestartsTxnPush               telemetry.CounterWithMetric
    RestartsUnknown               telemetry.CounterWithMetric

TxnMetrics holds all metrics relating to KV transactions.

func MakeTxnMetrics Uses

func MakeTxnMetrics(histogramWindow time.Duration) TxnMetrics

MakeTxnMetrics returns a TxnMetrics struct that contains metrics whose windowed portions retain data for approximately histogramWindow.

Package kvcoord imports 52 packages (graph) and is imported by 30 packages. Updated 2020-08-12. Refresh now. Tools for package owners.