github.com/vescale/zgraph@v0.0.0-20230410094002-959c02d50f95/storage/kv/interfaces.go (about)

     1  // Copyright 2022 zGraph Authors. All rights reserved.
     2  //
     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
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     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.
    14  
    15  package kv
    16  
    17  import (
    18  	"context"
    19  )
    20  
    21  type Storage interface {
    22  	VersionProvider
    23  
    24  	Begin() (Transaction, error)
    25  	Snapshot(ver Version) (Snapshot, error)
    26  	Close() error
    27  }
    28  
    29  // Iterator is the interface for a SnapshotIter on KV db.
    30  type Iterator interface {
    31  	Valid() bool
    32  	Key() Key
    33  	Value() []byte
    34  	Next() error
    35  	Close()
    36  }
    37  
    38  // Getter is the interface for the Get method.
    39  type Getter interface {
    40  	// Get gets the value for key k from kv db.
    41  	// If corresponding kv pair does not exist, it returns nil and ErrNotExist.
    42  	Get(ctx context.Context, k Key) ([]byte, error)
    43  }
    44  
    45  // BatchGetter is the interface for BatchGet.
    46  type BatchGetter interface {
    47  	// BatchGet gets a batch of values.
    48  	BatchGet(ctx context.Context, keys []Key) (map[string][]byte, error)
    49  }
    50  
    51  // Retriever is the interface wraps the basic Get and Seek methods.
    52  type Retriever interface {
    53  	Getter
    54  	// Iter creates an Iterator positioned on the first entry that k <= entry's key.
    55  	// If such entry is not found, it returns an invalid Iterator with no error.
    56  	// It yields only keys that < upperBound. If upperBound is nil, it means the upperBound is unbounded.
    57  	// The Iterator must be Closed after use.
    58  	Iter(lowerBound Key, upperBound Key) (Iterator, error)
    59  
    60  	// IterReverse creates a reversed Iterator positioned on the first entry which key is less than k.
    61  	// The returned SnapshotIter will iterate from greater key to smaller key.
    62  	// If k is nil, the returned SnapshotIter will be positioned at the last key.
    63  	IterReverse(lowerBound Key, upperBound Key) (Iterator, error)
    64  }
    65  
    66  // Mutator is the interface wraps the basic Set and Delete methods.
    67  type Mutator interface {
    68  	// Set sets the value for key k as v into kv db.
    69  	// v must NOT be nil or empty, otherwise it returns ErrCannotSetNilValue.
    70  	Set(k Key, v []byte) error
    71  	// Delete removes the entry for key k from kv db.
    72  	Delete(k Key) error
    73  }
    74  
    75  // RetrieverMutator is the interface that groups Retriever and Mutator interfaces.
    76  type RetrieverMutator interface {
    77  	Retriever
    78  	Mutator
    79  }
    80  
    81  type Transaction interface {
    82  	RetrieverMutator
    83  
    84  	StartVer() Version
    85  	// Snapshot returns the Snapshot binding to this transaction.
    86  	Snapshot() Snapshot
    87  	// BatchGet gets kv from the memory buffer of statement and transaction, and the kv storage.
    88  	// Do not use len(value) == 0 or value == nil to represent non-exist.
    89  	// If a key doesn't exist, there shouldn't be any corresponding entry in the result map.
    90  	BatchGet(ctx context.Context, keys []Key) (map[string][]byte, error)
    91  	// Size returns sum of keys and values length.
    92  	Size() int
    93  	// Len returns the number of entries in the DB.
    94  	Len() int
    95  	// Reset reset the Transaction to initial states.
    96  	Reset()
    97  	// Commit commits the transaction operations to KV db.
    98  	Commit(context.Context) error
    99  	// Rollback undoes the transaction operations to KV db.
   100  	Rollback() error
   101  	// String implements fmt.Stringer interface.
   102  	String() string
   103  }
   104  
   105  // Snapshot defines the interface for the snapshot fetched from KV db.
   106  type Snapshot interface {
   107  	Retriever
   108  	BatchGetter
   109  	// StartVer returns the start verstion of the current snapshot.
   110  	StartVer() Version
   111  }