1 // Copyright 2019 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
5 // Package storage defines storage interfaces for and a basic implementation of a checksum database.
10 // A Storage is a transaction key-value storage system.
11 type Storage interface {
12 // ReadOnly runs f in a read-only transaction.
13 // It is equivalent to ReadWrite except that the
14 // transaction's BufferWrite method will fail unconditionally.
15 // (The implementation may be able to optimize the
16 // transaction if it knows at the start that no writes will happen.)
17 ReadOnly(ctx context.Context, f func(context.Context, Transaction) error) error
19 // ReadWrite runs f in a read-write transaction.
20 // If f returns an error, the transaction aborts and returns that error.
21 // If f returns nil, the transaction attempts to commit and then then return nil.
22 // Otherwise it tries again. Note that f may be called multiple times and that
23 // the result only describes the effect of the final call to f.
24 // The caller must take care not to use any state computed during
25 // earlier calls to f, or even the last call to f when an error is returned.
26 ReadWrite(ctx context.Context, f func(context.Context, Transaction) error) error
29 // A Transaction provides read and write operations within a transaction,
30 // as executed by Storage's ReadOnly or ReadWrite methods.
31 type Transaction interface {
32 // ReadValue reads the value associated with a single key.
33 // If there is no value associated with that key, ReadKey returns an empty value.
34 // An error is only returned for problems accessing the storage.
35 ReadValue(ctx context.Context, key string) (value string, err error)
37 // ReadValues reads the values associated with the given keys.
38 // If there is no value stored for a given key, ReadValues returns an empty value for that key.
39 // An error is only returned for problems accessing the storage.
40 ReadValues(ctx context.Context, keys []string) (values []string, err error)
42 // BufferWrites buffers the given writes,
43 // to be applied at the end of the transaction.
44 // BufferWrites panics if this is a ReadOnly transaction.
45 // It returns an error if it detects any other problems.
46 // The behavior of multiple writes buffered using the same key
47 // is undefined: it may return an error or not.
48 BufferWrites(writes []Write) error
51 // A Write is a single change to be applied at the end of a read-write transaction.
52 // A Write with an empty value deletes the value associated with the given key.