cache

package module
v2.0.0-...-2e01499 Latest Latest
Warning

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

Go to latest
Published: Jun 25, 2023 License: Apache-2.0 Imports: 20 Imported by: 0

README

cache

cache is a Go cache manager. It can use many cache adapters. The repo is inspired by database/sql .

How to install?

go get github.com/beego/beego/v2/client/cache

What adapters are supported?

As of now this cache support memory, Memcache and Redis.

How to use it?

First you must import it

import (
	"github.com/beego/beego/v2/client/cache"
)

Then init a Cache (example with memory)

bm := cache.NewMemoryCache(60)	

Use it like this:

bm.Put("astaxie", 1, 10 * time.Second)
bm.Get("astaxie")
bm.IsExist("astaxie")
bm.Delete("astaxie")

interval means the gc time. The cache will check at each time interval, whether item has expired.

Memcache

Memcache use the gomemcache client.

Redis

Redis use the redigo client.

Documentation

Index

Constants

View Source
const (
	MinUint32 uint32 = 0
	MinUint64 uint64 = 0
)

Variables

View Source
var (
	ErrIncrementOverflow = berror.Error(IncrementOverflow, "this incr invocation will overflow.")
	ErrDecrementOverflow = berror.Error(DecrementOverflow, "this decr invocation will overflow.")
	ErrNotIntegerType    = berror.Error(NotIntegerType, "item val is not (u)int (u)int32 (u)int64")
)
View Source
var (
	ErrKeyExpired  = berror.Error(KeyExpired, "the key is expired")
	ErrKeyNotExist = berror.Error(KeyNotExist, "the key isn't exist")
)
View Source
var (
	FileCachePath           = "cache"     // cache directory
	FileCacheFileSuffix     = ".bin"      // cache file suffix
	FileCacheDirectoryLevel = 2           // cache file deep level if auto generated cache files.
	FileCacheEmbedExpiry    time.Duration // cache expire time, default is no expire forever.
)

FileCache Config

View Source
var CreateFileCacheDirFailed = berror.DefineCode(4002009, moduleName, "CreateFileCacheDirFailed", `
Beego failed to create file cache directory. There are two cases:
1. You pass invalid CachePath parameter. Please check your input.
2. Beego doesn't have the permission to create this directory. Please check your file mode.
`)
View Source
var DecrementOverflow = berror.DefineCode(4002005, moduleName, "DecrementOverflow", `
The decrement operation will overflow.
`)
View Source
var DeleteFileCacheItemFailed = berror.DefineCode(5002001, moduleName, "DeleteFileCacheItemFailed", `
Beego try to delete file cache item failed. 
Please check whether Beego generated file correctly. 
And then confirm whether this file is already deleted by other processes or other people.
`)
View Source
var DialFailed = berror.DefineCode(5002005, moduleName, "DialFailed", `
When Beego try to dial to remote servers, it failed. Please check your connection info and network state, server state.
`)
View Source
var GobEncodeDataFailed = berror.DefineCode(4002013, moduleName, "GobEncodeDataFailed", `
Beego could not encode the data to GOB byte array. In general, the data type is invalid. 
For example, GOB doesn't support function type.
Basic types, string, structure, structure pointer are supported. 
`)
View Source
var IncrementOverflow = berror.DefineCode(4002004, moduleName, "IncrementOverflow", `
The increment operation will overflow.
`)
View Source
var InvalidFileCachePath = berror.DefineCode(4002010, moduleName, "InvalidFilePath", `
The file path of FileCache is invalid. Please correct the config.
`)
View Source
var InvalidGobEncodedData = berror.DefineCode(4002012, moduleName, "InvalidEncodedData", `
The data is invalid. When you try to decode the invalid data, you got this error.
Please confirm that the data is encoded by GOB correctly.
`)
View Source
var InvalidInitParameters = berror.DefineCode(4002025, moduleName, "InvalidInitParameters", `
Invalid init cache parameters.
You can check the related function to confirm that if you pass correct parameters or configure to initiate a Cache instance.
`)
View Source
var InvalidLoadFunc = berror.DefineCode(4002023, moduleName, "InvalidLoadFunc", `
Invalid load function for read-through pattern decorator.
You should pass a valid(non-nil) load function when initiate the decorator instance.
`)
View Source
var InvalidMemCacheValue = berror.DefineCode(4002019, moduleName, "InvalidMemCacheValue", `
The value must be string or byte[], please check your input.
`)
View Source
var InvalidSsdbCacheValue = berror.DefineCode(4002022, moduleName, "InvalidSsdbCacheValue", `
SSDB cache only accept string value. Please check your input.
`)
View Source
var KeyExpired = berror.DefineCode(4002014, moduleName, "KeyExpired", `
Cache key is expired.
You should notice that, a key is expired and then it may be deleted by GC goroutine. 
So when you query a key which may be expired, you may got this code, or KeyNotExist.
`)
View Source
var KeyNotExist = berror.DefineCode(4002015, moduleName, "KeyNotExist", `
Key not found.
`)
View Source
var LoadFuncFailed = berror.DefineCode(4002024, moduleName, "LoadFuncFailed", `
Failed to load data, please check whether the loadfunc is correct
`)
View Source
var MemCacheCurdFailed = berror.DefineCode(5002002, moduleName, "MemCacheError", `
When you want to get, put, delete key-value from remote memcache servers, you may get error:
1. You pass invalid servers address, so Beego could not connect to remote server;
2. The servers address is correct, but there is some net issue. Typically there is some firewalls between application and memcache server;
3. Key is invalid. The key's length should be less than 250 and must not contains special characters;
4. The response from memcache server is invalid;
`)
View Source
var MultiGetFailed = berror.DefineCode(4002016, moduleName, "MultiGetFailed", `
Get multiple keys failed. Please check the detail msg to find out the root cause.
`)
View Source
var NotIntegerType = berror.DefineCode(4002006, moduleName, "NotIntegerType", `
The type of value is not (u)int (u)int32 (u)int64. 
When you want to call Incr or Decr function of Cache API, you must confirm that the value's type is one of (u)int (u)int32 (u)int64.
`)
View Source
var PersistCacheFailed = berror.DefineCode(4002026, moduleName, "PersistCacheFailed", `
Failed to execute the StoreFunc.
Please check the log to make sure the StoreFunc works for the specific key and value.
`)
View Source
var ReadFileCacheContentFailed = berror.DefineCode(4002011, moduleName, "ReadFileCacheContentFailed", `
Usually you won't got this error. It means that Beego cannot read the data from the file.
You need to check whether the file exist. Sometimes it may be deleted by other processes.
If the file exists, please check the permission that Beego is able to read data from the file.
`)
View Source
var RedisCacheCurdFailed = berror.DefineCode(5002003, moduleName, "RedisCacheCurdFailed", `
When Beego uses client to send request to redis server, it failed.
1. The server addresses is invalid;
2. Network issue, firewall issue or network is unstable;
3. Client failed to manage connection. In extreme cases, Beego's redis client didn't maintain connections correctly, for example, Beego try to send request via closed connection;
4. The request are huge and redis server spent too much time to process it, and client is timeout;

In general, if you always got this error whatever you do, in most cases, it was caused by network issue. 
You could check your network state, and confirm that firewall rules are correct.
`)
View Source
var SsdbBadResponse = berror.DefineCode(5002007, moduleName, "SsdbBadResponse", `
The reponse from SSDB server is invalid. 
Usually it indicates something wrong on server side.
`)
View Source
var SsdbCacheCurdFailed = berror.DefineCode(5002006, moduleName, "SsdbCacheCurdFailed", `
When you try to use SSDB cache, it failed. There are many cases:
1. servers unavailable;
2. network issue, including network unstable, firewall;
3. connection issue;
4. request are huge and servers spent too much time to process it, got timeout;
`)

Functions

func FileGetContents

func FileGetContents(filename string) ([]byte, error)

FileGetContents Reads bytes from a file. if non-existent, create this file.

func FilePutContents

func FilePutContents(filename string, content []byte) error

FilePutContents puts bytes into a file. if non-existent, create this file.

func GetBool

func GetBool(v interface{}) bool

GetBool converts interface to bool.

func GetFloat64

func GetFloat64(v interface{}) float64

GetFloat64 converts interface to float64.

func GetInt

func GetInt(v interface{}) int

GetInt converts interface to int.

func GetInt64

func GetInt64(v interface{}) int64

GetInt64 converts interface to int64.

func GetString

func GetString(v interface{}) string

GetString converts interface to string.

func GobDecode

func GobDecode(data []byte, to *FileCacheItem) error

GobDecode Gob decodes a file cache item.

func GobEncode

func GobEncode(data interface{}) ([]byte, error)

GobEncode Gob encodes a file cache item.

Types

type BloomFilter

type BloomFilter interface {
	Test(data string) bool
	Add(data string)
}

type BloomFilterCache

type BloomFilterCache struct {
	Cache
	BloomFilter
	// contains filtered or unexported fields
}

func NewBloomFilterCache

func NewBloomFilterCache(cache Cache, ln func(context.Context, string) (any, error), blm BloomFilter,
	expiration time.Duration,
) (*BloomFilterCache, error)

func (*BloomFilterCache) Get

func (bfc *BloomFilterCache) Get(ctx context.Context, key string) (any, error)

type Cache

type Cache interface {
	// Get a cached value by key.
	Get(ctx context.Context, key string) (interface{}, error)
	// GetMulti is a batch version of Get.
	GetMulti(ctx context.Context, keys []string) ([]interface{}, error)
	// Put Set a cached value with key and expire time.
	Put(ctx context.Context, key string, val interface{}, timeout time.Duration) error
	// Delete cached value by key.
	// Should not return error if key not found
	Delete(ctx context.Context, key string) error
	// Incr Increment a cached int value by key, as a counter.
	Incr(ctx context.Context, key string) error
	// Decr Decrement a cached int value by key, as a counter.
	Decr(ctx context.Context, key string) error
	// IsExist Check if a cached value exists or not.
	// if key is expired, return (false, nil)
	IsExist(ctx context.Context, key string) (bool, error)
	// ClearAll Clear all cache.
	ClearAll(ctx context.Context) error
}

Cache interface contains all behaviors for cache adapter.

func NewFileCache

func NewFileCache(opts ...FileCacheOptions) (Cache, error)

NewFileCache creates a new file cache with no config. The level and expiry need to be set in the method StartAndGC as config string.

func NewMemoryCache

func NewMemoryCache(interval int) Cache

NewMemoryCache returns a new MemoryCache.

func NewRandomExpireCache

func NewRandomExpireCache(adapter Cache, opts ...RandomExpireCacheOption) Cache

NewRandomExpireCache return random expire cache struct

func NewReadThroughCache

func NewReadThroughCache(cache Cache, expiration time.Duration,
	loadFunc func(ctx context.Context, key string) (any, error),
) (Cache, error)

NewReadThroughCache create readThroughCache

func NewSingleflightCache

func NewSingleflightCache(c Cache, expiration time.Duration,
	loadFunc func(ctx context.Context, key string) (any, error),
) (Cache, error)

NewSingleflightCache create SingleflightCache

type FileCache

type FileCache struct {
	CachePath      string
	FileSuffix     string
	DirectoryLevel int
	EmbedExpiry    int
}

FileCache is cache adapter for file storage.

func (*FileCache) ClearAll

func (fc *FileCache) ClearAll(context.Context) error

ClearAll cleans cached files (not implemented)

func (*FileCache) Decr

func (fc *FileCache) Decr(ctx context.Context, key string) error

Decr decreases cached int value.

func (*FileCache) Delete

func (fc *FileCache) Delete(ctx context.Context, key string) error

Delete file cache value.

func (*FileCache) Get

func (fc *FileCache) Get(ctx context.Context, key string) (interface{}, error)

Get value from file cache. if nonexistent or expired return an empty string.

func (*FileCache) GetMulti

func (fc *FileCache) GetMulti(ctx context.Context, keys []string) ([]interface{}, error)

GetMulti gets values from file cache. if nonexistent or expired return an empty string.

func (*FileCache) Incr

func (fc *FileCache) Incr(ctx context.Context, key string) error

Incr increases cached int value. fc value is saved forever unless deleted.

func (*FileCache) Init

func (fc *FileCache) Init() error

Init makes new a dir for file cache if it does not already exist

func (*FileCache) IsExist

func (fc *FileCache) IsExist(ctx context.Context, key string) (bool, error)

IsExist checks if value exists.

func (*FileCache) Put

func (fc *FileCache) Put(ctx context.Context, key string, val interface{}, timeout time.Duration) error

Put value into file cache. timeout: how long this file should be kept in ms if timeout equals fc.EmbedExpiry(default is 0), cache this item forever.

type FileCacheItem

type FileCacheItem struct {
	Data       interface{}
	Lastaccess time.Time
	Expired    time.Time
}

FileCacheItem is basic unit of file cache adapter which contains data and expire time.

type FileCacheOptions

type FileCacheOptions func(c *FileCache)

func FileCacheWithCachePath

func FileCacheWithCachePath(cachePath string) FileCacheOptions

FileCacheWithCachePath configures cachePath for FileCache

func FileCacheWithDirectoryLevel

func FileCacheWithDirectoryLevel(directoryLevel int) FileCacheOptions

FileCacheWithDirectoryLevel configures directoryLevel for FileCache

func FileCacheWithEmbedExpiry

func FileCacheWithEmbedExpiry(fileCacheEmbedExpiry int) FileCacheOptions

FileCacheWithEmbedExpiry configures fileCacheEmbedExpiry for FileCache

func FileCacheWithFileSuffix

func FileCacheWithFileSuffix(fileSuffix string) FileCacheOptions

FileCacheWithFileSuffix configures fileSuffix for FileCache

type MemoryCache

type MemoryCache struct {
	sync.RWMutex

	Every int // run an expiration check Every clock time
	// contains filtered or unexported fields
}

MemoryCache is a memory cache adapter. Contains a RW locker for safe map storage.

func (*MemoryCache) ClearAll

func (bc *MemoryCache) ClearAll(context.Context) error

ClearAll deletes all cache in memory.

func (*MemoryCache) Decr

func (bc *MemoryCache) Decr(ctx context.Context, key string) error

Decr decreases counter in memory.

func (*MemoryCache) Delete

func (bc *MemoryCache) Delete(ctx context.Context, key string) error

Delete cache in memory. If the key is not found, it will not return error

func (*MemoryCache) Get

func (bc *MemoryCache) Get(ctx context.Context, key string) (interface{}, error)

Get returns cache from memory. If non-existent or expired, return nil.

func (*MemoryCache) GetMulti

func (bc *MemoryCache) GetMulti(ctx context.Context, keys []string) ([]interface{}, error)

GetMulti gets caches from memory. If non-existent or expired, return nil.

func (*MemoryCache) Incr

func (bc *MemoryCache) Incr(ctx context.Context, key string) error

Incr increases cache counter in memory. Supports int,int32,int64,uint,uint32,uint64.

func (*MemoryCache) IsExist

func (bc *MemoryCache) IsExist(ctx context.Context, key string) (bool, error)

IsExist checks if cache exists in memory.

func (*MemoryCache) Put

func (bc *MemoryCache) Put(ctx context.Context, key string, val interface{}, timeout time.Duration) error

Put puts cache into memory. If lifespan is 0, it will never overwrite this value unless restarted

type MemoryItem

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

MemoryItem stores memory cache item.

type RandomExpireCache

type RandomExpireCache struct {
	Cache
	// contains filtered or unexported fields
}

RandomExpireCache prevent cache batch invalidation Cache random time offset expired

func (*RandomExpireCache) Put

func (rec *RandomExpireCache) Put(ctx context.Context, key string, val interface{}, timeout time.Duration) error

Put random time offset expired

type RandomExpireCacheOption

type RandomExpireCacheOption func(*RandomExpireCache)

RandomExpireCacheOption implement genreate random time offset expired option

func WithRandomExpireCacheOffsetFunc

func WithRandomExpireCacheOffsetFunc(fn func() time.Duration) RandomExpireCacheOption

WithRandomExpireCacheOffsetFunc returns a RandomExpireCacheOption that configures the offset function

type SingleflightCache

type SingleflightCache struct {
	Cache
	// contains filtered or unexported fields
}

SingleflightCache This is a very simple decorator mode

func (*SingleflightCache) Get

func (s *SingleflightCache) Get(ctx context.Context, key string) (any, error)

Get In the Get method, single flight is used to load data and write back the cache.

type WriteThroughCache

type WriteThroughCache struct {
	Cache
	// contains filtered or unexported fields
}

func NewWriteThroughCache

func NewWriteThroughCache(cache Cache, fn func(ctx context.Context, key string, val any) error) (*WriteThroughCache, error)

func (*WriteThroughCache) Set

func (w *WriteThroughCache) Set(ctx context.Context, key string, val any, expiration time.Duration) error

Directories

Path Synopsis
internal/mock
Package mock is a generated GoMock package.
Package mock is a generated GoMock package.

Jump to

Keyboard shortcuts

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