cache

package
v6.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 21, 2026 License: GPL-3.0 Imports: 15 Imported by: 0

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

Examples

Constants

View Source
const HeaderByteSize = 4 + 8

HeaderByteSize is the total size of a cache item's header in bytes.

View Source
const Magic uint32 = 3735928559 // 0xdeadbeef

Magic is the first bytes of a cache item's header. It is always set to 0xdeadbeef.

Variables

View Source
var ErrCanceled = errors.New("write canceled")
View Source
var ErrIncompatibleVersion = errors.New("incompatible version")
View Source
var ErrInvalidMagic = errors.New("invalid magic number")
View Source
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

func (*Item) Decode

func (i *Item) Decode(value any) (err error)

func (*Item) Encode

func (i *Item) Encode(value any) (err error)

type Locator

type Locator interface {
	CacheLocations() (string, string, string)
}

Locator is a struct implementing the Locator interface. It can describe its location in the cache

type Marshaler

type Marshaler interface {
	MarshalCache(writer io.Writer) error
}

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(&timestamp); 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.

func (*Optional[T]) Get

func (o *Optional[T]) Get() *T

Get returns pointer to the value that was unmarshaled. We cannot simply set o.Value to point to the value read, because nil pointers cannot be dereferenced.

func (*Optional[T]) MarshalCache

func (o *Optional[T]) MarshalCache(writer io.Writer) (err error)

func (*Optional[T]) UnmarshalCache

func (o *Optional[T]) UnmarshalCache(fileVersion uint64, reader io.Reader) (err error)

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

var NoCache *Store = nil

NoCache indicates that we are not caching or reading from the cache

func NewStore

func NewStore(options *StoreOptions) (*Store, error)

func (*Store) Decache

func (s *Store) Decache(locators []Locator, procFunc, skipFunc func(*locations.ItemInfo) bool) error

func (*Store) Enabled

func (s *Store) Enabled() bool

func (*Store) IsFinal

func (s *Store) IsFinal(ts base.Timestamp) bool

func (*Store) ReadFromStore

func (s *Store) ReadFromStore(value Locator) error

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) Remove

func (s *Store) Remove(value Locator) error

func (*Store) SetLatest

func (s *Store) SetLatest(ts base.Timestamp)

func (*Store) Stat

func (s *Store) Stat(value Locator) (*locations.ItemInfo, error)

func (*Store) Write

func (s *Store) Write(value Locator) error

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 StoreLocation

type StoreLocation uint
const (
	FsCache StoreLocation = iota
	MemoryCache
)

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.

type Unmarshaler

type Unmarshaler interface {
	UnmarshalCache(vers uint64, reader io.Reader) error
}

Unmarshaler is a struct implementing Unmarshaler can be read from binary by calling UnmarshalCache

Directories

Path Synopsis
Package locations determines a cache item's location (either in memory or on disc)
Package locations determines a cache item's location (either in memory or on disc)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL