cache

package
v2.0.5 Latest Latest
Warning

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

 Go to latest Published: Jul 30, 2022 License: Apache-2.0 Imports: 19 Imported by: 37

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

bm, err := cache.NewCache("memory", `{"interval":60}`)

Use it like this:

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

Memory adapter

Configure memory adapter like this:

{"interval":60}

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

Memcache adapter

Memcache adapter use the gomemcache client.

Configure like this:

{"conn":"127.0.0.1:11211"}

Redis adapter

Redis adapter use the redigo client.

Configure like this:

{"conn":":6039"}

Documentation

Overview

Package cache provide a Cache interface and some implement engine Usage:

import( 

"github.com/beego/beego/v2/client/cache"

)

bm, err := cache.NewCache("memory", `{"interval":60}`)

Use it like this: 

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

 more docs http://beego.vip/docs/module/cache.md

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 DefaultEvery = 60 // 1 minute

DefaultEvery sets a timer for how often to recycle the expired cache items in memory (in seconds)

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 DuplicateAdapter = berror.DefineCode(4002002, moduleName, "DuplicateAdapter", `
You register two adapter with same name. In beego cache module, one name one adapter.
Once you got this error, please check the error stack, search adapter 
`)
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 InvalidConnection = berror.DefineCode(5002004, moduleName, "InvalidConnection", `
The connection is invalid. Please check your connection info, network, firewall.
You could simply uses ping, telnet or write some simple tests to test network.
`)
View Source 
var InvalidFileCacheDirectoryLevelCfg = berror.DefineCode(4002007, moduleName, "InvalidFileCacheDirectoryLevelCfg", `
You pass invalid DirectoryLevel parameter when you try to StartAndGC file cache instance.
This parameter must be a integer, and please check your input.
`)
View Source 
var InvalidFileCacheEmbedExpiryCfg = berror.DefineCode(4002008, moduleName, "InvalidFileCacheEmbedExpiryCfg", `
You pass invalid EmbedExpiry parameter when you try to StartAndGC file cache instance.
This parameter must be a integer, and please check your input.
`)
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 InvalidMemCacheCfg = berror.DefineCode(4002018, moduleName, "InvalidMemCacheCfg", `
The config is invalid. Please check your input, it must be json string and contains "conn" field.
`)
View Source 
var InvalidMemCacheValue = berror.DefineCode(4002019, moduleName, "InvalidMemCacheValue", `
The value must be string or byte[], please check your input.
`)
View Source 
var InvalidMemoryCacheCfg = berror.DefineCode(4002017, moduleName, "InvalidMemoryCacheCfg", `
The config is invalid. Please check your input. It must be a json string.
`)
View Source 
var InvalidRedisCacheCfg = berror.DefineCode(4002020, moduleName, "InvalidRedisCacheCfg", `
The config must be json string, and has "conn" field.
`)
View Source 
var InvalidSsdbCacheCfg = berror.DefineCode(4002021, moduleName, "InvalidSsdbCacheCfg", `
The config must be json string, and has "conn" field. The value of "conn" field should be "host:port".
"port" must be a valid integer.
`)
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 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 NilCacheAdapter = berror.DefineCode(4002001, moduleName, "NilCacheAdapter", `
It means that you register cache adapter by pass nil.
A cache adapter is an instance of Cache interface. 
`)
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 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;
`)
View Source 
var UnknownAdapter = berror.DefineCode(4002003, moduleName, "UnknownAdapter", `
Unknown adapter, do you forget to register the adapter?
You must register adapter before use it. For example, if you want to use redis implementation, 
you must import the cache/redis package.
`)

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.

func Register 

func Register(name string, adapter Instance)

Register makes a cache adapter available by the adapter name. If Register is called twice with the same name or if driver is nil, it panics.

Types

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
	// StartAndGC Start gc routine based on config string settings.
	StartAndGC(config string) error
}

Cache interface contains all behaviors for cache adapter. usage: 

cache.Register("file",cache.NewFileCache) // this operation is run in init method of file.go.
c,err := cache.NewCache("file","{....}")
c.Put("key",value, 3600 * time.Second)
v := c.Get("key")

c.Incr("counter")  // now is 1
c.Incr("counter")  // now is 2
count := c.Get("counter").(int)

func NewCache 

func NewCache(adapterName, config string) (adapter Cache, err error)

NewCache creates a new cache driver by adapter name and config string. config: must be in JSON format such as {"interval":360}. Starts gc automatically.

func NewFileCache 

func NewFileCache() Cache

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() Cache

NewMemoryCache returns a new MemoryCache.

func NewRandomExpireCache added in v2.0.5 

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

NewRandomExpireCache return random expire cache struct

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.

func (*FileCache) StartAndGC 

func (fc *FileCache) StartAndGC(config string) error

StartAndGC starts gc for file cache. config must be in the format {CachePath:"/cache","FileSuffix":".bin","DirectoryLevel":"2","EmbedExpiry":"0"}

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 Instance 

type Instance func() Cache

Instance is a function create a new Cache Instance

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

func (*MemoryCache) StartAndGC 

func (bc *MemoryCache) StartAndGC(config string) error

StartAndGC starts memory cache. Checks expiration in every clock time.

type MemoryItem 

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

MemoryItem stores memory cache item.

type RandomExpireCache added in v2.0.5 

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

RandomExpireCache prevent cache batch invalidation Cache random time offset expired

func (*RandomExpireCache) Put added in v2.0.5 

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

Put random time offset expired

type RandomExpireCacheOption added in v2.0.5 

type RandomExpireCacheOption func(*RandomExpireCache)

RandomExpireCacheOption implement genreate random time offset expired option

func WithOffsetFunc added in v2.0.5 

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

WithOffsetFunc returns a RandomExpireCacheOption that configures the offset function

Source Files

View all Source files

Directories

Path Synopsis
Package memcache for cache provider
 Package memcache for cache provider
Package redis for cache provider
 Package redis for cache provider

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.