docs: cache-wrapping and virtual store (#8102)

* docs: cache-wrapping and virtual store

* Finish the docs update

* Update docs/building-modules/msg-services.md

Co-authored-by: Amaury <amaury.martiny@protonmail.com>

* Update docs/building-modules/msg-services.md

Co-authored-by: Aleksandr Bezobchuk <alexanderbez@users.noreply.github.com>

Co-authored-by: Amaury <amaury.martiny@protonmail.com>
Co-authored-by: Aleksandr Bezobchuk <alexanderbez@users.noreply.github.com>

store/README.md

@@ -34,7 +34,7 @@ type Store struct {
 }
 ```
 
-`cachemulti.Store` cache wraps all substores in its constructor and hold them in `Store.stores`. `Store.GetKVStore()` returns the store from `Store.stores`, and `Store.Write()` recursively calls `CacheWrap.Write()` on the substores.
+`cachemulti.Store` branches all substores in its constructor and hold them in `Store.stores`. `Store.GetKVStore()` returns the store from `Store.stores`, and `Store.Write()` recursively calls `CacheWrap.Write()` on the substores.
 
 ## DBAdapter
 

store/cache/cache.go

@@ -89,7 +89,7 @@ func (cmgr *CommitKVStoreCacheManager) Reset() {
 	}
 }
 
-// CacheWrap returns the inter-block cache as a cache-wrapped CommitKVStore.
+// CacheWrap implements the CacheWrapper interface
 func (ckv *CommitKVStoreCache) CacheWrap() types.CacheWrap {
 	return cachekv.NewStore(ckv)
 }

store/cachekv/store.go

@@ -35,6 +35,7 @@ type Store struct {
 
 var _ types.CacheKVStore = (*Store)(nil)
 
+// NewStore creates a new Store object
 func NewStore(parent types.KVStore) *Store {
 	return &Store{
 		cache:         make(map[string]*cValue),
@@ -44,12 +45,12 @@ func NewStore(parent types.KVStore) *Store {
 	}
 }
 
-// Implements Store.
+// GetStoreType implements Store.
 func (store *Store) GetStoreType() types.StoreType {
 	return store.parent.GetStoreType()
 }
 
-// Implements types.KVStore.
+// Get implements types.KVStore.
 func (store *Store) Get(key []byte) (value []byte) {
 	store.mtx.Lock()
 	defer store.mtx.Unlock()
@@ -68,7 +69,7 @@ func (store *Store) Get(key []byte) (value []byte) {
 	return value
 }
 
-// Implements types.KVStore.
+// Set implements types.KVStore.
 func (store *Store) Set(key []byte, value []byte) {
 	store.mtx.Lock()
 	defer store.mtx.Unlock()
@@ -80,13 +81,13 @@ func (store *Store) Set(key []byte, value []byte) {
 	store.setCacheValue(key, value, false, true)
 }
 
-// Implements types.KVStore.
+// Has implements types.KVStore.
 func (store *Store) Has(key []byte) bool {
 	value := store.Get(key)
 	return value != nil
 }
 
-// Implements types.KVStore.
+// Delete implements types.KVStore.
 func (store *Store) Delete(key []byte) {
 	store.mtx.Lock()
 	defer store.mtx.Unlock()
@@ -135,10 +136,7 @@ func (store *Store) Write() {
 	store.sortedCache = list.New()
 }
 
-//----------------------------------------
-// To cache-wrap this Store further.
-
-// Implements CacheWrapper.
+// CacheWrap implements CacheWrapper.
 func (store *Store) CacheWrap() types.CacheWrap {
 	return NewStore(store)
 }
@@ -151,12 +149,12 @@ func (store *Store) CacheWrapWithTrace(w io.Writer, tc types.TraceContext) types
 //----------------------------------------
 // Iteration
 
-// Implements types.KVStore.
+// Iterator implements types.KVStore.
 func (store *Store) Iterator(start, end []byte) types.Iterator {
 	return store.iterator(start, end, true)
 }
 
-// Implements types.KVStore.
+// ReverseIterator implements types.KVStore.
 func (store *Store) ReverseIterator(start, end []byte) types.Iterator {
 	return store.iterator(start, end, false)
 }

store/cachemulti/store.go

@@ -14,7 +14,7 @@ import (
 //----------------------------------------
 // Store
 
-// Store holds many cache-wrapped stores.
+// Store holds many branched stores.
 // Implements MultiStore.
 // NOTE: a Store (and MultiStores in general) should never expose the
 // keys for the substores.
@@ -31,7 +31,7 @@ var _ types.CacheMultiStore = Store{}
 
 // NewFromKVStore creates a new Store object from a mapping of store keys to
 // CacheWrapper objects and a KVStore as the database. Each CacheWrapper store
-// is cache-wrapped.
+// is a branched store.
 func NewFromKVStore(
 	store types.KVStore, stores map[types.StoreKey]types.CacheWrapper,
 	keys map[string]types.StoreKey, traceWriter io.Writer, traceContext types.TraceContext,
@@ -56,7 +56,7 @@ func NewFromKVStore(
 }
 
 // NewStore creates a new Store object from a mapping of store keys to
-// CacheWrapper objects. Each CacheWrapper store is cache-wrapped.
+// CacheWrapper objects. Each CacheWrapper store is a branched store.
 func NewStore(
 	db dbm.DB, stores map[types.StoreKey]types.CacheWrapper, keys map[string]types.StoreKey,
 	traceWriter io.Writer, traceContext types.TraceContext,
@@ -136,7 +136,7 @@ func (cms Store) CacheMultiStore() types.CacheMultiStore {
 // TODO: The store implementation can possibly be modified to support this as it
 // seems safe to load previous versions (heights).
 func (cms Store) CacheMultiStoreWithVersion(_ int64) (types.CacheMultiStore, error) {
-	panic("cannot cache-wrap cached multi-store with a version")
+	panic("cannot branch cached multi-store with a version")
 }
 
 // GetStore returns an underlying Store by key.

store/dbadapter/store.go

@@ -75,7 +75,7 @@ func (Store) GetStoreType() types.StoreType {
 	return types.StoreTypeDB
 }
 
-// CacheWrap cache wraps the underlying store.
+// CacheWrap branches the underlying store.
 func (dsa Store) CacheWrap() types.CacheWrap {
 	return cachekv.NewStore(dsa)
 }

store/mem/store.go

@@ -35,7 +35,7 @@ func (s Store) GetStoreType() types.StoreType {
 	return types.StoreTypeMemory
 }
 
-// CacheWrap cache wraps the underlying store.
+// CacheWrap branches the underlying store.
 func (s Store) CacheWrap() types.CacheWrap {
 	return cachekv.NewStore(s)
 }

store/rootmulti/store.go

@@ -41,7 +41,7 @@ const (
 )
 
 // Store is composed of many CommitStores. Name contrasts with
-// cacheMultiStore which is for cache-wrapping other MultiStores. It implements
+// cacheMultiStore which is used for branching other MultiStores. It implements
 // the CommitMultiStore interface.
 type Store struct {
 	db             dbm.DB
@@ -404,7 +404,7 @@ func (rs *Store) CacheWrapWithTrace(_ io.Writer, _ types.TraceContext) types.Cac
 	return rs.CacheWrap()
 }
 
-// CacheMultiStore cache-wraps the multi-store and returns a CacheMultiStore.
+// CacheMultiStore creates ephemeral branch of the multi-store and returns a CacheMultiStore.
 // It implements the MultiStore interface.
 func (rs *Store) CacheMultiStore() types.CacheMultiStore {
 	stores := make(map[types.StoreKey]types.CacheWrapper)
@@ -841,7 +841,7 @@ func (rs *Store) loadCommitStoreFromParams(key types.StoreKey, id types.CommitID
 		if rs.interBlockCache != nil {
 			// Wrap and get a CommitKVStore with inter-block caching. Note, this should
 			// only wrap the primary CommitKVStore, not any store that is already
-			// cache-wrapped as that will create unexpected behavior.
+			// branched as that will create unexpected behavior.
 			store = rs.interBlockCache.GetStoreCache(key, store)
 		}
 

store/tracekv/store.go

@@ -161,14 +161,14 @@ func (tkv *Store) GetStoreType() types.StoreType {
 	return tkv.parent.GetStoreType()
 }
 
-// CacheWrap implements the KVStore interface. It panics as a Store
-// cannot be cache wrapped.
+// CacheWrap implements the KVStore interface. It panics because a Store
+// cannot be branched.
 func (tkv *Store) CacheWrap() types.CacheWrap {
 	panic("cannot CacheWrap a Store")
 }
 
 // CacheWrapWithTrace implements the KVStore interface. It panics as a
-// Store cannot be cache wrapped.
+// Store cannot be branched.
 func (tkv *Store) CacheWrapWithTrace(_ io.Writer, _ types.TraceContext) types.CacheWrap {
 	panic("cannot CacheWrapWithTrace a Store")
 }

store/types/store.go

@@ -104,12 +104,12 @@ func (s *StoreUpgrades) RenamedFrom(key string) string {
 type MultiStore interface {
 	Store
 
-	// Cache wrap MultiStore.
+	// Branches MultiStore into a cached storage object.
 	// NOTE: Caller should probably not call .Write() on each, but
 	// call CacheMultiStore.Write().
 	CacheMultiStore() CacheMultiStore
 
-	// CacheMultiStoreWithVersion cache-wraps the underlying MultiStore where
+	// CacheMultiStoreWithVersion branches the underlying MultiStore where
 	// each stored is loaded at a specific version (height).
 	CacheMultiStoreWithVersion(version int64) (CacheMultiStore, error)
 
@@ -138,7 +138,7 @@ type CacheMultiStore interface {
 	Write() // Writes operations to underlying KVStore
 }
 
-// A non-cache MultiStore.
+// CommitMultiStore is an interface for a MultiStore without cache capabilities.
 type CommitMultiStore interface {
 	Committer
 	MultiStore
@@ -218,12 +218,12 @@ type KVStore interface {
 	ReverseIterator(start, end []byte) Iterator
 }
 
-// Alias iterator to db's Iterator for convenience.
+// Iterator is an alias db's Iterator for convenience.
 type Iterator = dbm.Iterator
 
-// CacheKVStore cache-wraps a KVStore.  After calling .Write() on
-// the CacheKVStore, all previously created CacheKVStores on the
-// object expire.
+// CacheKVStore branches a KVStore and provides read cache functionality.
+// After calling .Write() on the CacheKVStore, all previously created
+// CacheKVStores on the object expire.
 type CacheKVStore interface {
 	KVStore
 
@@ -231,7 +231,7 @@ type CacheKVStore interface {
 	Write()
 }
 
-// Stores of MultiStore must implement CommitStore.
+// CommitKVStore is an interface for MultiStore.
 type CommitKVStore interface {
 	Committer
 	KVStore
@@ -240,9 +240,9 @@ type CommitKVStore interface {
 //----------------------------------------
 // CacheWrap
 
-// CacheWrap makes the most appropriate cache-wrap. For example,
-// IAVLStore.CacheWrap() returns a CacheKVStore. CacheWrap should not return
-// a Committer, since Commit cache-wraps make no sense. It can return KVStore,
+// CacheWrap is the most appropriate interface for store ephemeral branching and cache.
+// For example, IAVLStore.CacheWrap() returns a CacheKVStore. CacheWrap should not return
+// a Committer, since Commit ephemeral store make no sense. It can return KVStore,
 // HeapStore, SpaceStore, etc.
 type CacheWrap interface {
 	// Write syncs with the underlying store.
@@ -256,10 +256,10 @@ type CacheWrap interface {
 }
 
 type CacheWrapper interface {
-	// CacheWrap cache wraps.
+	// CacheWrap branches a store.
 	CacheWrap() CacheWrap
 
-	// CacheWrapWithTrace cache wraps with tracing enabled.
+	// CacheWrapWithTrace branches a store with tracing enabled.
 	CacheWrapWithTrace(w io.Writer, tc TraceContext) CacheWrap
 }