cmd.go

// Copyright 2019 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 apply

// Command is a command that has been successfully replicated through raft
// by being durably committed to the raft log of a quorum of peers in a raft
// group.
type Command interface {
	// Index is the log index of the corresponding raft entry.
	Index() uint64
	// IsTrivial returns whether the command can apply in a batch.
	IsTrivial() bool
	// IsLocal returns whether the command was locally proposed.
	IsLocal() bool
}

// CheckedCommand is a command that has been checked to see whether it can
// apply successfully or not. Committing an entry in a raft log and having
// the command in that entry succeed are similar but not equivalent concepts.
// A successfully committed entry may contain a command that the replicated
// state machine decides to reject (deterministically).
type CheckedCommand interface {
	Command
	// Rejected returns whether the command was rejected.
	Rejected() bool
}

// AppliedCommand is a command that has been applied to the replicated state
// machine. A command is considered "applied" if it has been staged in a
// Batch which has been committed and had its side-effects run on the state
// machine. If the command was rejected (see CheckedCommand), applying the
// command will likely be a no-op, but that is up to the implementation of
// the state machine.
type AppliedCommand interface {
	CheckedCommand
	// AckOutcomeAndFinish acknowledges the outcome of the command to its
	// client. It also signals that the application of the command has
	// completed.
	AckOutcomeAndFinish() error
}

// CommandIteratorBase is a common interface extended by all iterator and
// list variants. It is exported so its methods are displayed in godoc when
// it is embedded in other interfaces.
type CommandIteratorBase interface {
	// Valid returns whether the iterator is pointing at a valid element.
	Valid() bool
	// Next advances the iterator. Should not be called if valid is false.
	Next()
	// NewList returns a new empty command list. Usages of the list will
	// always advance the iterator before pushing into to the list, so
	// implementors are free to share backing memory between the two.
	NewList() CommandList
	// NewCheckedList returns a new empty checked command list. Usages
	// of the list will always advance the iterator before pushing into
	// to the list, so implementors are free to share backing memory
	// between the two.
	NewCheckedList() CheckedCommandList
	// NewAppliedList returns a new empty applied command list. Usages
	// of the list will always advance the iterator before pushing into
	// to the list, so implementors are free to share backing memory
	// between the two.
	NewAppliedList() AppliedCommandList
	// Close closes the iterator. Once closed, it must not be used.
	Close()
}

// CommandIterator is an iterator over replicated commands.
type CommandIterator interface {
	CommandIteratorBase
	// cur returns the command that the iterator is currently pointing at.
	// Should not be called if valid is false.
	Cur() Command
}

// CommandList is a list of replicated commands.
type CommandList interface {
	CommandIterator
	// Append pushes the command on to the back of the list.
	Append(Command)
}

// CheckedCommandIterator is an iterator over checked replicated
// commands.
type CheckedCommandIterator interface {
	CommandIteratorBase
	// cur returns the checked command that the iterator is currently
	// pointing at. Should not be called if valid is false.
	CurChecked() CheckedCommand
}

// CheckedCommandList is a list of checked replicated commands.
type CheckedCommandList interface {
	CheckedCommandIterator
	// AppendChecked pushes the checked command on to the back of the list.
	AppendChecked(CheckedCommand)
}

// AppliedCommandIterator is an iterator over applied replicated commands.
type AppliedCommandIterator interface {
	CommandIteratorBase
	// cur returns the applied command that the iterator is currently
	// pointing at. Should not be called if valid is false.
	CurApplied() AppliedCommand
}

// AppliedCommandList is a list of applied replicated commands.
type AppliedCommandList interface {
	AppliedCommandIterator
	// AppendApplied pushes the applied command on to the back of the list.
	AppendApplied(AppliedCommand)
}

// takeWhileCmdIter returns an iterator that yields commands based on a
// predicate. It will call the predicate on each command in the provided
// iterator and yield elements while it returns true. The function does
// NOT close the provided iterator, but does drain it of any commands
// that are moved to the returned iterator.
func takeWhileCmdIter(iter CommandIterator, pred func(Command) bool) CommandIterator {
	ret := iter.NewList()
	for iter.Valid() {
		cmd := iter.Cur()
		if !pred(cmd) {
			break
		}
		iter.Next()
		ret.Append(cmd)
	}
	return ret
}

// mapCmdIter returns an iterator that contains the result of each command
// from the provided iterator transformed by a closure. The closure is
// responsible for converting Commands into CheckedCommand. The function
// closes the provided iterator.
func mapCmdIter(
	iter CommandIterator, fn func(Command) (CheckedCommand, error),
) (CheckedCommandIterator, error) {
	defer iter.Close()
	ret := iter.NewCheckedList()
	for iter.Valid() {
		checked, err := fn(iter.Cur())
		if err != nil {
			return nil, err
		}
		iter.Next()
		ret.AppendChecked(checked)
	}
	return ret, nil
}

// mapCheckedCmdIter returns an iterator that contains the result of each
// command from the provided iterator transformed by a closure. The closure
// is responsible for converting CheckedCommand into AppliedCommand. The
// function closes the provided iterator.
func mapCheckedCmdIter(
	iter CheckedCommandIterator, fn func(CheckedCommand) (AppliedCommand, error),
) (AppliedCommandIterator, error) {
	defer iter.Close()
	ret := iter.NewAppliedList()
	for iter.Valid() {
		applied, err := fn(iter.CurChecked())
		if err != nil {
			return nil, err
		}
		iter.Next()
		ret.AppendApplied(applied)
	}
	return ret, nil
}

// forEachCheckedCmdIter calls a closure on each command in the provided
// iterator. The function closes the provided iterator.
func forEachCheckedCmdIter(iter CheckedCommandIterator, fn func(CheckedCommand) error) error {
	defer iter.Close()
	for iter.Valid() {
		if err := fn(iter.CurChecked()); err != nil {
			return err
		}
		iter.Next()
	}
	return nil
}

// forEachAppliedCmdIter calls a closure on each command in the provided
// iterator. The function closes the provided iterator.
func forEachAppliedCmdIter(iter AppliedCommandIterator, fn func(AppliedCommand) error) error {
	defer iter.Close()
	for iter.Valid() {
		if err := fn(iter.CurApplied()); err != nil {
			return err
		}
		iter.Next()
	}
	return nil
}