bigcache

README

tRPC-Go bigcache plugin

Encapsulate the bigcache library from the GitHub community to use with the tRPC-Go framework.

bigcache encapsulates a high-performance third-party local cache library in Golang. We enhances its functionality by adding support for additional value types, making it more convenient to use.

Example usage

package main

import (
    "fmt"
    "strconv"

    "trpc.group/trpc-go/trpc-database/bigcache"
)

func main() {
    cache := bigcache.New(
        // Set the number of shards, default is 256.
        bigcache.WithShards(1024),
        // Set the life window, default is 7 days.
        bigcache.WithLifeWindow(time.Hour),
        // Set the clean window, default is 1 minute.
        bigcache.WithCleanWindow(-1*time.Second),
        // Set the maximum number of entries in the window, default is 200,000.
		    // A smaller value can reduce memory usage during initialization, and it's only used during initialization.
        bigcache.WithMaxEntriesInWindow(50000),
        // Set the maximum entry size in bytes, default is 30.
		    // A smaller value can reduce memory usage during initialization, and it's only used during initialization.
        bigcache.WithMaxEntrySize(20),
    )
    var err error
    var v string
    for j := 0; j < 1000000; j++ {
        key := fmt.Sprintf("k%010d", j)
        v = "v" + strconv.Itoa(j)
        // write data
        err = cache.Set(key, v)
        if err != nil {
            fmt.Println(err)
        }
        // get data
        val, err := cache.GetBytes(key)
        if err != nil {
            fmt.Println(err)
        }
        fmt.Printf("got value: %+v", val)
        if j%10000 == 0 {
            fmt.Println(v)
        }
    }
}

Overview

1. Encapsulate the interface to add support for types other than []byte. The current supported value types include []byte, string, int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, float32, float64, bool, and error formats.
2. The GC overhead is negligible and CPU consumption is significantly reduced when dealing with cache data in the order of millions. For more details, please refer to the original README.md under the section How it works.
3. Key features: support for Iterator to access cache, Len to query the number of data entries, Capacity to query the size of the cache in bytes, and Status to check cache hit status.
4. Logging utilizes the capabilities provided by the tRPC-Go framework.
5. Add the compare_test directory for performance comparison with Sync.Map and localcache. For more information, please refer to the README.md file in that directory.

Documentation

Overview

Package bigcache encapsulates a low garbage collection (GC) consuming local cache library named BigCache.

Index

• Constants
• func InitDefaultConfig(cfg Config) bigcache.Config
• func ToInterface(s string, to interface{}) (interface{}, error)
• func ToString(i interface{}) (string, error)
• type BigCache
  • func New(opt ...Option) (BigCache, error)
  • func (c *BigCache) Capacity() int
  • func (c *BigCache) Close() error
  • func (c *BigCache) Delete(key string) error
  • func (c *BigCache) Get(key string, val interface{}, serializationType int) (err error)
  • func (c *BigCache) GetBytes(key string) ([]byte, error)
  • func (c *BigCache) GetBytesWithInfo(key string) ([]byte, bigcache.Response, error)
  • func (c *BigCache) GetWithInfo(key string, val interface{}, serializationType int) (bigcache.Response, error)
  • func (c *BigCache) Iterator() *bigcache.EntryInfoIterator
  • func (c *BigCache) KeyMetadata(key string) bigcache.Metadata
  • func (c *BigCache) Len() int
  • func (c *BigCache) Reset() error
  • func (c *BigCache) Set(key string, val interface{}, serializationType ...int) error
  • func (c *BigCache) Stats() bigcache.Stats
• type Config
  • func DefaultConfig() Config
• type Option
  • func WithCleanWindow(t time.Duration) Option
  • func WithHardMaxCacheSize(m int) Option
  • func WithHasher(h bigcache.Hasher) Option
  • func WithLifeWindow(t time.Duration) Option
  • func WithLogger(l bigcache.Logger) Option
  • func WithMaxEntriesInWindow(i int) Option
  • func WithMaxEntrySize(i int) Option
  • func WithOnRemoveCallback(f func(key string, entry []byte)) Option
  • func WithOnRemoveWithMetadataCallback(f func(key string, entry []byte, keyMetadata bigcache.Metadata)) Option
  • func WithOnRemoveWithReasonCallback(f func(key string, entry []byte, reason bigcache.RemoveReason)) Option
  • func WithShards(i int) Option
  • func WithStatsEnabled(s bool) Option
  • func WithVerbose(v bool) Option

Constants

const (
	// ErrEntryNotFound entry not found
	ErrEntryNotFound = -1
)

Functions

func InitDefaultConfig

func InitDefaultConfig(cfg Config) bigcache.Config

InitDefaultConfig initializes the config used by the third-party library BigCache. You can directly modify the bigcache.Config if necessary.

func ToInterface

func ToInterface(s string, to interface{}) (interface{}, error)

ToInterface converts a string type to the corresponding interface types such as bool, float, int, uint, error, etc.

func ToString

func ToString(i interface{}) (string, error)

ToString converts bool, float, int, uint, error, and other types to string type.

Types

type BigCache

type BigCache struct {
	// contains filtered or unexported fields
}

BigCache is the local cache struct, encapsulating the corresponding struct of third-party library.

func New

func New(opt ...Option) (BigCache, error)

New initializes a BigCache with default parameters. If the initialization fails, it returns an error, which is then handled by the business layer.

func (*BigCache) Capacity

func (c *BigCache) Capacity() int

Capacity returns the number of bytes used in the cache.

func (*BigCache) Close

func (c *BigCache) Close() error

Close sends a shutdown signal, exits the clean coroutine, and ensures that it can be garbage collected.

func (*BigCache) Delete

func (c *BigCache) Delete(key string) error

Delete deletes the key

func (*BigCache) Get

func (c *BigCache) Get(key string, val interface{}, serializationType int) (err error)

Get gets the value by the given key. If the key does not exist, it returns ErrEntryNotFound. The value is automatically parsed using the specified serialization type.

func (*BigCache) GetBytes

func (c *BigCache) GetBytes(key string) ([]byte, error)

GetBytes gets the raw bytes by the given key. If the key does not exist, it returns ErrEntryNotFound.

func (*BigCache) GetBytesWithInfo

func (c *BigCache) GetBytesWithInfo(key string) ([]byte, bigcache.Response, error)

GetBytesWithInfo gets the raw bytes by the given key. If the key does not exist, it returns ErrEntryNotFound, along with additional information indicating whether the entry has expired.

func (*BigCache) GetWithInfo

func (c *BigCache) GetWithInfo(key string, val interface{}, serializationType int) (bigcache.Response, error)

GetWithInfo gets the value by the key. If the entry has been removed or expired, it returns ErrEntryNotFound, along with additional information indicating whether the entry has expired. The value is automatically parsed using the specified serialization type.

func (*BigCache) Iterator

func (c *BigCache) Iterator() *bigcache.EntryInfoIterator

Iterator returns an iterator that can traverse the entire cache.

func (*BigCache) KeyMetadata

func (c *BigCache) KeyMetadata(key string) bigcache.Metadata

KeyMetadata returns the hit count for the key.

func (*BigCache) Len

func (c *BigCache) Len() int

Len returns the number of data entries in the cache

func (*BigCache) Reset

func (c *BigCache) Reset() error

Reset clears all shards of the cache.

func (*BigCache) Set

func (c *BigCache) Set(key string, val interface{}, serializationType ...int) error

Set saves a key-value pair, which may fail if the value format is not supported. The data is automatically packaged using the input serialization type.

func (*BigCache) Stats

func (c *BigCache) Stats() bigcache.Stats

Stats returns the statistical data for cache hits.

type Config

type Config struct {
	// Shards is the number of shards, must be a power of 2, such as 2, 4, 8, 16, 32, etc.
	Shards int
	// LifeWindow is the life window of data in the cache.
	LifeWindow time.Duration
	// CleanWindow is the window between each cleanup of expired data, set to a value less than 0 to disable cleanup.
	// Default value is 1 second.
	CleanWindow time.Duration
	// MaxEntriesInWindow is the maximum number of data entries, only used when initializing cache shards.
	MaxEntriesInWindow int
	// MaxEntrySize is the maximum size of a value in bytes, only used when initializing cache shards.
	MaxEntrySize int
	// StatsEnabled enables tracking of hit count for individual keys when set to true.
	StatsEnabled bool
	// Verbose enables output of memory allocation information when set to true.
	Verbose bool
	// HardMaxCacheSize is the maximum cache size in MB.
	// It's set to prevent excessive memory allocation and avoid OOM errors,
	// and it only takes effect when set to a value greater than 0.
	HardMaxCacheSize int
	Logger           bigcache.Logger
	// OnRemove is a callback fired when the oldest entry is removed because of its expiration time or no space left
	// for the new entry, or because delete was called.
	// Default value is nil which means no callback and it prevents from unwrapping the oldest entry.
	// ignored if OnRemoveWithMetadata is specified.
	OnRemove func(key string, entry []byte)
	// OnRemoveWithMetadata is a callback fired when the oldest entry is removed because of its expiration time
	// or no space left for the new entry, or because delete was called.
	// A structure representing details about that specific entry.
	// Default value is nil which means no callback and it prevents from unwrapping the oldest entry.
	OnRemoveWithMetadata func(key string, entry []byte, keyMetadata bigcache.Metadata)
	// OnRemoveWithReason is a callback fired when the oldest entry is removed because of its expiration time
	// or no space left for the new entry, or because delete was called.
	// A constant representing the reason will be passed through.
	// Default value is nil which means no callback and it prevents from unwrapping the oldest entry.
	// Ignored if OnRemove is specified.
	OnRemoveWithReason func(key string, entry []byte, reason bigcache.RemoveReason)
	// Hasher used to map between string keys and unsigned 64bit integers, by default fnv64 hashing is used.
	Hasher bigcache.Hasher
}

Config is a configuration parameter that can be used to initialize BigCache.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig initializes the default values for the main config parameters. The default life window is set to 7 days, and the default cleaning window is set to 1 minute.

type Option

type Option func(*Config)

Option declares the option functions of the cache

func WithCleanWindow

func WithCleanWindow(t time.Duration) Option

WithCleanWindow sets the clean window

func WithHardMaxCacheSize

func WithHardMaxCacheSize(m int) Option

WithHardMaxCacheSize sets the maximum cache size in MB. It's set to prevent excessive memory allocation and avoid OOM errors, and it only takes effect when set to a value greater than 0.

func WithHasher

func WithHasher(h bigcache.Hasher) Option

WithHasher sets hasher interface

func WithLifeWindow

func WithLifeWindow(t time.Duration) Option

WithLifeWindow sets the life window

func WithLogger

func WithLogger(l bigcache.Logger) Option

WithLogger sets the logger

func WithMaxEntriesInWindow

func WithMaxEntriesInWindow(i int) Option

WithMaxEntriesInWindow sets the maximum number of data entries, used only during initialization, and affects the minimum memory usage.

func WithMaxEntrySize

func WithMaxEntrySize(i int) Option

WithMaxEntrySize sets the maximum size of a value in bytes, used only during initialization, and affects the minimum memory usage.

func WithOnRemoveCallback

func WithOnRemoveCallback(f func(key string, entry []byte)) Option

WithOnRemoveCallback sets OnRemove callback function

func WithOnRemoveWithMetadataCallback

func WithOnRemoveWithMetadataCallback(f func(key string, entry []byte, keyMetadata bigcache.Metadata)) Option

WithOnRemoveWithMetadataCallback sets OnRemoveWithMetadata callback function

func WithOnRemoveWithReasonCallback

func WithOnRemoveWithReasonCallback(f func(key string, entry []byte, reason bigcache.RemoveReason)) Option

WithOnRemoveWithReasonCallback sets OnRemoveWithReason callback function

func WithShards

func WithShards(i int) Option

WithShards sets the number of shards

func WithStatsEnabled

func WithStatsEnabled(s bool) Option

WithStatsEnabled sets whether to enable tracking of hit count for individual keys.

func WithVerbose

func WithVerbose(v bool) Option

WithVerbose sets whether to enable output of memory allocation information.