Documentation
¶
Index ¶
Constants ¶
This section is empty.
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:
- to access data it must use the passed in state.Store.
- it must set the responseMeta.Index to an index greater than opts.GetMinQueryIndex if the results return by the query have changed.
- 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:
- only set responseMeta.Index to an index greater than opts.GetMinQueryIndex when the results returned by the query have changed.
- 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 ¶
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.
Source Files