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. 4 5 // Package storage defines storage interfaces for and a basic implementation of a checksum database. 6 package storage 7 8 import "context" 9 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 18 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 27 } 28 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) 36 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) 41 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 49 } 50 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. 53 type Write struct { 54 Key string 55 Value string 56 } 57