Documentation
¶
Overview ¶
Package cache implements the new caching code
Example ¶
// This example shows the usage of Locator interface, which is higher level
// abstraction over Cache(un)Marshaler
// Let's create something to store
block := &ExampleBlock{
BlockNumber: 4436721,
Name: "Test block",
Timestamp: 1688667358,
}
// We made `BlockNumber` our cache ID
_, id, _ := block.CacheLocations()
fmt.Println(id)
// we will store it in memory cache (if StoreOptions is nil, then file system
// cache is used)
store, err := NewStore(&StoreOptions{Location: MemoryCache})
if err != nil {
panic(err)
}
if err := store.Write(block); err != nil {
panic(err)
}
readFromCache := &ExampleBlock{
BlockNumber: 4436721,
}
if err := store.ReadFromStore(readFromCache); err != nil {
panic(err)
}
fmt.Printf("%+v\n", readFromCache)
Output: 4436721 &{BlockNumber:4436721 Date: Name:Test block Timestamp:1688667358}
Index ¶
- Constants
- Variables
- type Item
- type Locator
- type Marshaler
- type Optional
- type Store
- func (s *Store) Decache(locators []Locator, procFunc, skipFunc func(*locations.ItemInfo) bool) error
- func (s *Store) Enabled() bool
- func (s *Store) IsFinal(ts base.Timestamp) bool
- func (s *Store) ReadFromStore(value Locator) error
- func (s *Store) Remove(value Locator) error
- func (s *Store) SetLatest(ts base.Timestamp)
- func (s *Store) Stat(value Locator) (*locations.ItemInfo, error)
- func (s *Store) Write(value Locator) error
- func (s *Store) WriteToStore(data Locator, cacheType walk.CacheType, ts base.Timestamp, conditions ...bool) error
- type StoreLocation
- type StoreOptions
- type Storer
- type Unmarshaler
Examples ¶
Constants ¶
const HeaderByteSize = 4 + 8
HeaderByteSize is the total size of a cache item's header in bytes.
const Magic uint32 = 3735928559 // 0xdeadbeef
Magic is the first bytes of a cache item's header. It is always set to 0xdeadbeef.
Variables ¶
var ErrCanceled = errors.New("write canceled")
var ErrIncompatibleVersion = errors.New("incompatible version")
var ErrInvalidMagic = errors.New("invalid magic number")
var ErrReadOnly = errors.New("cache is read-only")
Functions ¶
This section is empty.
Types ¶
type Item ¶
type Item struct {
// contains filtered or unexported fields
}
func NewItem ¶
func NewItem(rw io.ReadWriter) *Item
type Locator ¶
Locator is a struct implementing the Locator interface. It can describe its location in the cache
type Marshaler ¶
Marshaler is a struct implementing the Marshaler interface. It can be written to binary by calling MarshalCache
Example ¶
// We start with a simple example of storing uint64 serialized to binary
// First, we create a fake file (we need something that implements io.ReadWriter)
timestampsCacheFile := new(bytes.Buffer)
// Now we point our cache item to use this "file". This is temporary, it will be
// handled by some higher abstraction (CacheLayout perhaps?)
timestampsCacheItem := NewItem(timestampsCacheFile)
// We encode (serialize to binary) the value. The cache header is written automatically
// by Encode()
if err := timestampsCacheItem.Encode(uint64(1688667358)); err != nil {
panic(err)
}
// Let's read the value
var timestamp uint64
// Decode checks cache header automatically
if err := timestampsCacheItem.Decode(×tamp); err != nil {
panic(err)
}
fmt.Println(timestamp)
// Now we will write a structure which implements Cache(un)Marshaler
block := &ExampleBlock{
BlockNumber: 17636511,
Date: "2023-07-06",
Name: "Nice Block",
Timestamp: 1688667358,
}
// Again, we create a fake file and cache item linked to it. And again, it'll be
// more automated later
blocksCacheFile := new(bytes.Buffer)
blocksCacheItem := NewItem(blocksCacheFile)
// We call Encode() to serialize to Cache header is written by default
if err := blocksCacheItem.Encode(block); err != nil {
panic(err)
}
// Now we can read the struct back
decodedBlock := &ExampleBlock{}
if err := blocksCacheItem.Decode(decodedBlock); err != nil {
panic(err)
}
fmt.Printf("%+v\n", decodedBlock)
Output: 1688667358 &{BlockNumber:17636511 Date: Name:Nice Block Timestamp:1688667358}
type Optional ¶
type Optional[T any] struct { Value *T // contains filtered or unexported fields }
Optional is used to read/write values that can be missing. Most of the case, it will be pointers to articulated objects. Optional.MarshalCache first write a boolean indicating if the value is present or not. If it is not present, nothing is written next. However, if it is present the value will be written using the standard path through WriteValue.
When reading a missing value, we get a correct pointer zero value of nil instead of a pointer to initialized zero value from new(Type). new(Type) != nil.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store holds all information necessary to access the cache, no matter which concrete location (FS, IPFS, memory, etc.) is being used
func NewStore ¶
func NewStore(options *StoreOptions) (*Store, error)
func (*Store) ReadFromStore ¶
ReadFromStore retrieves value from a location defined by options.Location. If options is nil, then FileSystem is used. The value has to implement Locator interface, which provides information about in-cache path
func (*Store) Write ¶
Write saves value to a location defined by options.Location. If options is nil, then FileSystem is used. The value has to implement Locator interface, which provides information about in-cache path and ID.
func (*Store) WriteToStore ¶
func (s *Store) WriteToStore(data Locator, cacheType walk.CacheType, ts base.Timestamp, conditions ...bool) error
WriteToStore handles caching of any data type that implements the Locator interface. Precondition: Caller must ensure caching is enabled and provide all conditions (e.g., isFinal, isWritable).
type StoreOptions ¶
type StoreOptions struct {
Chain string
Location StoreLocation
RootDir string
Enabled bool
EnabledMap map[walk.CacheType]bool
Latest base.Timestamp
}
StoreOptions used by Store
type Storer ¶
type Storer interface {
// Writer returns io.WriteCloser for the given cache item
Writer(path string) (io.WriteCloser, error)
// Reader returns io.ReaderCloser for the given cache item
Reader(path string) (io.ReadCloser, error)
Remove(path string) error
Stat(path string) (*locations.ItemInfo, error)
}
Storer stores items in the given location. Cache is agnostic of the actual location of the items (files in FS terms) and Storer is responsible for all low-level work.