buffer.go

// Copyright 2021 The Cockroach Authors.
//
// Use of this software is governed by the Business Source License
// included in the file licenses/BSL.txt.
//
// As of the Change Date specified in that file, in accordance with
// the Business Source License, use of this software will be governed
// by the Apache License, Version 2.0, included in the file
// licenses/APL.txt.

package spanconfigsqlwatcher

import (
	"context"

	"github.com/cockroachdb/cockroach/pkg/kv/kvclient/rangefeed/rangefeedbuffer"
	"github.com/cockroachdb/cockroach/pkg/spanconfig"
	"github.com/cockroachdb/cockroach/pkg/sql/catalog/descpb"
	"github.com/cockroachdb/cockroach/pkg/util/hlc"
	"github.com/cockroachdb/cockroach/pkg/util/syncutil"
)

// buffer is a helper struct for the SQLWatcher. It buffers events generated by
// the SQLWatcher's rangefeeds over system.zones and system.descriptors. All
// methods lock internally so they can be called concurrently.
//
// The buffer tracks frontier timestamps for both these rangefeeds as well. It
// maintains the notion of the combined frontier timestamp computed as the
// minimum of the two. This is used when flushing the buffer periodically.
type buffer struct {
	mu struct {
		syncutil.Mutex

		// rangefeed.Buffer stores spanconfigsqlwatcher.Events.
		buffer *rangefeedbuffer.Buffer

		// rangefeedFrontiers tracks the frontier timestamps of individual
		// rangefeeds established by the SQLWatcher.
		rangefeedFrontiers [numRangefeeds]hlc.Timestamp
	}
}

// event is the unit produced by the rangefeeds the SQLWatcher establishes over
// system.zones and system.descriptors. It implements the rangefeedbuffer.Event
// interface.
type event struct {
	// timestamp at which the event was generated by the rangefeed.
	timestamp hlc.Timestamp

	// update captures information about the descriptor or zone that the
	// SQLWatcher has observed change.
	update spanconfig.SQLWatcherUpdate
}

// Timestamp implements the rangefeedbuffer.Event interface.
func (e event) Timestamp() hlc.Timestamp {
	return e.timestamp
}

// rangefeedKind is used to identify the distinct rangefeeds {descriptors,
// zones} established by the SQLWatcher.
type rangefeedKind int

const (
	zonesRangefeed rangefeedKind = iota
	descriptorsRangefeed

	// numRangefeeds should be listed last.
	numRangefeeds
)

// newBuffer constructs and returns a new buffer.
func newBuffer(limit int) *buffer {
	rangefeedBuffer := rangefeedbuffer.New(limit)
	eventBuffer := &buffer{}
	eventBuffer.mu.buffer = rangefeedBuffer
	return eventBuffer
}

// advance advances the frontier for the given rangefeed.
func (b *buffer) advance(rangefeed rangefeedKind, timestamp hlc.Timestamp) {
	b.mu.Lock()
	defer b.mu.Unlock()
	b.mu.rangefeedFrontiers[rangefeed].Forward(timestamp)
}

// add records the given event in the buffer.
func (b *buffer) add(ev event) error {
	b.mu.Lock()
	defer b.mu.Unlock()
	return b.mu.buffer.Add(ev)
}

// flush computes the combined frontier timestamp of the buffer and returns a
// list of unique spanconfig.SQLWatcherUpdates below this timestamp. The
// combined frontier timestamp is also returned.
func (b *buffer) flush(
	ctx context.Context,
) (updates []spanconfig.SQLWatcherUpdate, combinedFrontierTS hlc.Timestamp) {
	b.mu.Lock()
	defer b.mu.Unlock()
	seenIDs := make(map[descpb.ID]struct{})
	// First we determine the checkpoint timestamp, which is the minimum
	// checkpoint timestamp of all event types.
	combinedFrontierTS = hlc.MaxTimestamp
	for _, ts := range b.mu.rangefeedFrontiers {
		combinedFrontierTS.Backward(ts)
	}

	events := b.mu.buffer.Flush(ctx, combinedFrontierTS)

	for _, ev := range events {
		update := ev.(event).update
		// De-duplicate IDs from the returned result.
		if _, seen := seenIDs[update.ID]; !seen {
			seenIDs[update.ID] = struct{}{}
			updates = append(updates, update)
		}
	}
	return updates, combinedFrontierTS
}