1
// Copyright (c) 2014 Couchbase, Inc.
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
7
// http://www.apache.org/licenses/LICENSE-2.0
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
17
import "encoding/json"
19
// KVStore is an abstraction for working with KV stores. Note that
20
// in order to be used with the bleve.registry, it must also implement
21
// a constructor function of the registry.KVStoreConstructor type.
22
type KVStore interface {
24
// Writer returns a KVWriter which can be used to
25
// make changes to the KVStore. If a writer cannot
26
// be obtained a non-nil error is returned.
27
Writer() (KVWriter, error)
29
// Reader returns a KVReader which can be used to
30
// read data from the KVStore. If a reader cannot
31
// be obtained a non-nil error is returned.
32
Reader() (KVReader, error)
34
// Close closes the KVStore
38
// KVReader is an abstraction of an **ISOLATED** reader
39
// In this context isolated is defined to mean that
40
// writes/deletes made after the KVReader is opened
42
// Because there is usually a cost associated with
43
// keeping isolated readers active, users should
44
// close them as soon as they are no longer needed.
45
type KVReader interface {
47
// Get returns the value associated with the key
48
// If the key does not exist, nil is returned.
49
// The caller owns the bytes returned.
50
Get(key []byte) ([]byte, error)
52
// MultiGet retrieves multiple values in one call.
53
MultiGet(keys [][]byte) ([][]byte, error)
55
// PrefixIterator returns a KVIterator that will
56
// visit all K/V pairs with the provided prefix
57
PrefixIterator(prefix []byte) KVIterator
59
// RangeIterator returns a KVIterator that will
60
// visit all K/V pairs >= start AND < end
61
RangeIterator(start, end []byte) KVIterator
63
// Close closes the iterator
67
// KVIterator is an abstraction around key iteration
68
type KVIterator interface {
70
// Seek will advance the iterator to the specified key
73
// Next will advance the iterator to the next key
76
// Key returns the key pointed to by the iterator
77
// The bytes returned are **ONLY** valid until the next call to Seek/Next/Close
78
// Continued use after that requires that they be copied.
81
// Value returns the value pointed to by the iterator
82
// The bytes returned are **ONLY** valid until the next call to Seek/Next/Close
83
// Continued use after that requires that they be copied.
86
// Valid returns whether or not the iterator is in a valid state
89
// Current returns Key(),Value(),Valid() in a single operation
90
Current() ([]byte, []byte, bool)
92
// Close closes the iterator
96
// KVWriter is an abstraction for mutating the KVStore
97
// KVWriter does **NOT** enforce restrictions of a single writer
98
// if the underlying KVStore allows concurrent writes, the
99
// KVWriter interface should also do so, it is up to the caller
100
// to do this in a way that is safe and makes sense
101
type KVWriter interface {
103
// NewBatch returns a KVBatch for performing batch operations on this kvstore
106
// NewBatchEx returns a KVBatch and an associated byte array
107
// that's pre-sized based on the KVBatchOptions. The caller can
108
// use the returned byte array for keys and values associated with
109
// the batch. Once the batch is either executed or closed, the
110
// associated byte array should no longer be accessed by the
112
NewBatchEx(KVBatchOptions) ([]byte, KVBatch, error)
114
// ExecuteBatch will execute the KVBatch, the provided KVBatch **MUST** have
115
// been created by the same KVStore (though not necessarily the same KVWriter)
116
// Batch execution is atomic, either all the operations or none will be performed
117
ExecuteBatch(batch KVBatch) error
119
// Close closes the writer
123
// KVBatchOptions provides the KVWriter.NewBatchEx() method with batch
124
// preparation and preallocation information.
125
type KVBatchOptions struct {
126
// TotalBytes is the sum of key and value bytes needed by the
127
// caller for the entire batch. It affects the size of the
128
// returned byte array of KVWrite.NewBatchEx().
131
// NumSets is the number of Set() calls the caller will invoke on
135
// NumDeletes is the number of Delete() calls the caller will invoke
139
// NumMerges is the number of Merge() calls the caller will invoke
144
// KVBatch is an abstraction for making multiple KV mutations at once
145
type KVBatch interface {
147
// Set updates the key with the specified value
148
// both key and value []byte may be reused as soon as this call returns
151
// Delete removes the specified key
152
// the key []byte may be reused as soon as this call returns
155
// Merge merges old value with the new value at the specified key
156
// as prescribed by the KVStores merge operator
157
// both key and value []byte may be reused as soon as this call returns
158
Merge(key, val []byte)
160
// Reset frees resources for this batch and allows reuse
163
// Close frees resources
167
// KVStoreStats is an optional interface that KVStores can implement
168
// if they're able to report any useful stats
169
type KVStoreStats interface {
170
// Stats returns a JSON serializable object representing stats for this KVStore
171
Stats() json.Marshaler
173
StatsMap() map[string]interface{}
added
removed
index/store/kvstore.go
