Documentation ¶
Overview ¶
Package cachego provides an easy way to use foundation for your caching operations.
1. the basic usage:
// Create a cache for use. // We use option function to customize the creation of cache. // WithAutoGC means it will do gc automatically. cache := cachego.NewCache(cachego.WithAutoGC(10 * time.Minute)) // Set a new entry to cache. cache.Set("key", 666) // Get returns the value of this key. v, ok := cache.Get("key") fmt.Println(v, ok) // Output: 666 true // If you pass a not existed key to of method, nil and false will be returned. v, ok = cache.Get("not existed key") fmt.Println(v, ok) // Output: <nil> false // SetWithTTL sets an entry with expired time. // The unit of expired time is second. // See more information in example of ttl. cache.SetWithTTL("ttlKey", 123, 10) // Also, you can get value from cache first, then load it to cache if missed. // onMissed is usually used to get data from db or somewhere, so you can refresh the value in cache. cache.GetWithLoad("newKey", func() (data interface{}, ttl int64, err error) { return "newValue", 3, nil }) // We provide a way to set data to cache automatically, so you can access some hottest data extremely fast. stopAutoSet := cache.AutoSet("autoKey", 1*time.Second, func() (interface{}, error) { fmt.Println("AutoSet invoking...") return nil, nil }) // Keep main running in order to see what AutoSet did time.Sleep(5 * time.Second) stopAutoSet <- struct{}{}
2. the ttl usage:
// Create a cache and set an entry to cache. // The ttl is 3 seconds. cache := cachego.NewCache() cache.SetWithTTL("key", "value", 3) // Check if the key is alive. value, ok := cache.Get("key") fmt.Println(value, ok) // Output: value true // Wait for 5 seconds and check again. // Now the key is gone. time.Sleep(5 * time.Second) value, ok = cache.Get("key") fmt.Println(value, ok) // Output: <nil> false // However, the key is still in cache and you should remove it by Remove() or RemoveAll(). // So, we provide an automatic way to remove those who are dead. See more information in example of gc. cache.AutoGc(10 * time.Minute)
3. the gc usage:
// Create a cache and set an entry to cache. // The ttl is 1 second. cache := cachego.NewCache() cache.SetWithTTL("key", "value", 1) // Wait for 2 seconds and check the key. time.Sleep(2 * time.Second) // We can see this key is gone and we can't get it anymore. value, ok := cache.Get("key") fmt.Println(value, ok) // Output: <nil> false // However, the key still stores in cache and occupies the space. size := cache.Size() fmt.Println(size) // Output: 1 // We should call Gc() to clean up these dead entries. // Notice that this method will takes some CPU time to finish this task. cache.Gc() size = cache.Size() fmt.Println(size) // Output: 0 // Also, we provide an automatic way to do this job at fixed duration. // It returns a channel which can be used to stop this automatic job. // If you want to stop it, just send an true or false to the chan! stopAutoGc := cache.AutoGc(10 * time.Minute) stopAutoGc <- struct{}{}
4. the option usage:
// We use option function to customize the creation of cache. // You can just new it without options. cache := cachego.NewCache() cache.Set("key", "value") // You can set it to a cache with automatic gc if you want // Try WithAutoGC. cache = cachego.NewCache(cachego.WithAutoGC(10 * time.Minute)) // Also, you can add more than one option to cache. cache = cachego.NewCache(cachego.WithAutoGC(10 * time.Minute), cachego.WithMapSize(64), cachego.WithSegmentSize(4096)) // Every option has its function, and you should use them for some purposes. // WithDebugPoint runs a http server and registers some handlers for debug. cachego.WithDebugPoint(":8888") // try to visit :8888 time.Sleep(time.Minute)
Index ¶
- Constants
- type Cache
- func (c *Cache) AutoGc(duration time.Duration) chan<- struct{}
- func (c *Cache) AutoSet(key string, duration time.Duration, loadFunc func() (interface{}, error)) chan<- struct{}
- func (c *Cache) Gc()
- func (c *Cache) Get(key string) (interface{}, bool)
- func (c *Cache) GetWithLoad(key string, onMissed func() (data interface{}, ttl int64, err error)) (interface{}, error)
- func (c *Cache) Remove(key string)
- func (c *Cache) RemoveAll()
- func (c *Cache) Set(key string, value interface{})
- func (c *Cache) SetWithTTL(key string, value interface{}, ttl int64)
- func (c *Cache) Size() int
- type Option
Constants ¶
const (
// NeverDie means value.alive() returns true forever.
NeverDie = 0
)
const Version = "v0.2.3-alpha"
Version is the version string representation of cachego.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache is a struct of cache.
func (*Cache) AutoGc ¶ added in v0.1.0
AutoGc starts a goroutine to execute Gc() at fixed duration. It returns a channel which can be used to stop this goroutine.
func (*Cache) AutoSet ¶ added in v0.2.4
func (c *Cache) AutoSet(key string, duration time.Duration, loadFunc func() (interface{}, error)) chan<- struct{}
AutoSet starts a goroutine to execute Set() at fixed duration. It returns a channel which can be used to stop this goroutine.
func (*Cache) Gc ¶
func (c *Cache) Gc()
Gc removes dead entries in Cache. Notice that this method is weak-consistency and it doesn't guarantee 100% removed.
func (*Cache) GetWithLoad ¶ added in v0.2.2
func (c *Cache) GetWithLoad(key string, onMissed func() (data interface{}, ttl int64, err error)) (interface{}, error)
GetWithLoad fetches value of key from c first, and returns it if ok. It will invoke onMissed() to fetch data and load it to c if missed. The unit of ttl is second.
func (*Cache) Remove ¶
Remove removes the value of key. If this key is not existed, nothing will happen.
func (*Cache) RemoveAll ¶
func (c *Cache) RemoveAll()
RemoveAll removes all keys in Cache. Notice that this method is weak-consistency.
func (*Cache) SetWithTTL ¶ added in v0.1.0
SetWithTTL sets key and value to Cache with a ttl. The unit of ttl is second.
type Option ¶ added in v0.2.1
type Option func(cache *Cache)
Option is a function which initializes cache.
func WithAutoGC ¶ added in v0.2.1
WithAutoGC is an option turning on automatically gc.
func WithDebugPoint ¶ added in v0.2.1
WithDebugPoint runs a http server and registers some handlers for debug. Don't use it in production!
func WithMapSize ¶ added in v0.2.1
WithMapSize is an option setting initializing map size of cache.
func WithSegmentSize ¶ added in v0.2.1
WithSegmentSize is an option setting initializing segment size of cache.