blockingquery

Documentation

Index

• Variables
• func Query(fsmServer FSMServer, requestOpts RequestOptions, responseMeta ResponseMeta, ...) error
• type FSMServer
• type QueryFn
• type RequestOptions
• type ResponseMeta

Variables

var (
	ErrNotFound   = fmt.Errorf("no data found for query")
	ErrNotChanged = fmt.Errorf("data did not change for query")
)

Sentinel errors that must be used with blockingQuery

Functions

func Query

func Query(
	fsmServer FSMServer,
	requestOpts RequestOptions,
	responseMeta ResponseMeta,
	query QueryFn,
) error

Query performs a blocking query if opts.GetMinQueryIndex is greater than 0, otherwise performs a non-blocking query. Blocking queries will block until responseMeta.Index is greater than opts.GetMinQueryIndex, or opts.GetMaxQueryTime is reached. Non-blocking queries return immediately after performing the query.

If opts.GetRequireConsistent is true, blockingQuery will first verify it is still the cluster leader before performing the query.

The query function is expected to be a closure that has access to responseMeta so that it can set the Index. The actual result of the query is opaque to blockingQuery.

The query function can return ErrNotFound, which is a sentinel error. Returning ErrNotFound indicates that the query found no results, which allows blockingQuery to keep blocking until the query returns a non-nil error. The query function must take care to set the actual result of the query to nil in these cases, otherwise when blockingQuery times out it may return a previous result. ErrNotFound will never be returned to the caller, it is converted to nil before returning.

The query function can return ErrNotChanged, which is a sentinel error. This can only be returned on calls AFTER the first call, as it would not be possible to detect the absence of a change on the first call. Returning ErrNotChanged indicates that the query results are identical to the prior results which allows blockingQuery to keep blocking until the query returns a real changed result.

The query function must take care to ensure the actual result of the query is either left unmodified or explicitly left in a good state before returning, otherwise when blockingQuery times out it may return an incomplete or unexpected result. ErrNotChanged will never be returned to the caller, it is converted to nil before returning.

If query function returns any other error, the error is returned to the caller immediately.

The query function must follow these rules:

1. to access data it must use the passed in state.Store.
2. it must set the responseMeta.Index to an index greater than opts.GetMinQueryIndex if the results return by the query have changed.
3. any channels added to the memdb.WatchSet must unblock when the results returned by the query have changed.

To ensure optimal performance of the query, the query function should make a best-effort attempt to follow these guidelines:

1. only set responseMeta.Index to an index greater than opts.GetMinQueryIndex when the results returned by the query have changed.
2. any channels added to the memdb.WatchSet should only unblock when the results returned by the query have changed.

Types

type FSMServer

type FSMServer interface {
	ConsistentRead() error
	DecrementBlockingQueries() uint64
	GetShutdownChannel() chan struct{}
	GetState() *state.Store
	IncrementBlockingQueries() uint64
	RPCQueryTimeout(time.Duration) time.Duration
	SetQueryMeta(ResponseMeta, string)
}

FSMServer is interface into the stateful components of a Consul server, such as memdb or raft leadership.

type QueryFn

type QueryFn func(memdb.WatchSet, *state.Store) error

QueryFn is used to perform a query operation. See Server.blockingQuery for the requirements of this function.

type RequestOptions

type RequestOptions interface {
	GetToken() string
	GetMinQueryIndex() uint64
	GetMaxQueryTime() (time.Duration, error)
	GetRequireConsistent() bool
}

RequestOptions are options used by Server.blockingQuery to modify the behaviour of the query operation, or to populate response metadata.

type ResponseMeta

type ResponseMeta interface {
	SetLastContact(time.Duration)
	SetKnownLeader(bool)
	GetIndex() uint64
	SetIndex(uint64)
	SetResultsFilteredByACLs(bool)
}

ResponseMeta is an interface used to populate the response struct with metadata about the query and the state of the server.