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. // Both of them are set a key-value with no TTL. //cache.Set("key", 666, cachego.WithSetNoTTL()) cache.Set("key", 666) // Get returns the value of this key. v, err := cache.Get("key") fmt.Println(v, err) // Output: 666 <nil> // If you pass a not existed key to of method, nil and errNotFound will be returned. v, err = cache.Get("not existed key") if cachego.IsNotFound(err) { fmt.Println(v, err) // Output: <nil> cachego: key not found } // SetWithTTL sets an entry with expired time. // See more information in example of ttl. cache.Set("ttlKey", 123, cachego.WithSetTTL(10*time.Second)) // 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. // Notice ctx in onMissed is passed by Get option. onMissed := func(ctx context.Context) (data interface{}, err error) { return "newValue", nil } v, err = cache.Get("newKey", cachego.WithGetOnMissed(onMissed), cachego.WithGetTTL(3*time.Second)) fmt.Println(v, err) // Output: newValue <nil> // We provide a way to set data to cache automatically, so you can access some hottest data extremely fast. loadFunc := func(ctx context.Context) (interface{}, error) { fmt.Println("AutoSet invoking...") return nil, nil } stopCh := cache.AutoSet("autoKey", loadFunc, cachego.WithAutoSetGap(1*time.Second)) // Keep main running in order to see what AutoSet did. time.Sleep(5 * time.Second) stopCh <- struct{}{} // Stop AutoSet task
2. the ttl usage:
// Create a cache and set an entry to cache. cache := cachego.NewCache() cache.Set("key", "value", cachego.WithSetTTL(3*time.Second)) // Check if the key is alive. value, err := cache.Get("key") fmt.Println(value, err) // Output: value <nil> // Wait for 5 seconds and check again. // Now the key is gone. time.Sleep(5 * time.Second) value, err = cache.Get("key") fmt.Println(value, err) // Output: <nil> cachego: key not found // However, the key is still in cache, and you should remove it by Delete() or DeleteAll(). // 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. cache := cachego.NewCache() cache.Set("key", "value", cachego.WithSetTTL(1*time.Second)) value, err := cache.Get("key") fmt.Println(value, err) // Output: value <nil> // 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, err = cache.Get("key") fmt.Println(value, err) // Output: <nil> cachego: key not found // 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 take 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 one 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)) // Remember, some operations have their options, here is one example: cache.Get("key", cachego.WithGetOnMissed(func(ctx context.Context) (data interface{}, err error) { return "value", nil }))
5. the singleflight usage:
// In default, cachego enables single-flight mode in get operations. // Just use WithGetOnMissed option to enjoy the flight of data. cache := cachego.NewCache() var wg sync.WaitGroup for i := 0; i < 10; i++ { wg.Add(1) go func() { defer wg.Done() cache.Get("key1", cachego.WithGetOnMissed(func(ctx context.Context) (data interface{}, err error) { time.Sleep(30*time.Millisecond) // Assume I/O costs 30ms fmt.Println("key1: single-flight") return 123, nil })) }() } wg.Wait() // If you want to disable single-flight mode in some Get operations, try this: wg = sync.WaitGroup{} for i := 0; i < 10; i++ { wg.Add(1) go func() { defer wg.Done() cache.Get("key2", cachego.WithGetOnMissed(func(ctx context.Context) (data interface{}, err error) { time.Sleep(30 * time.Millisecond) // Assume I/O costs 30ms fmt.Println("key2: multi-flight") return 456, nil }), cachego.WithGetDisableSingleflight()) }() } wg.Wait() // Of course, we all know single-flight mode will decrease the success rate of loading data. // So you can disable it globally if you need. cache = cachego.NewCache(cachego.WithDisableSingleflight()) wg = sync.WaitGroup{} for i := 0; i < 10; i++ { wg.Add(1) go func() { defer wg.Done() cache.Get("key3", cachego.WithGetOnMissed(func(ctx context.Context) (data interface{}, err error) { time.Sleep(30 * time.Millisecond) // Assume I/O costs 30ms fmt.Println("key3: multi-flight") return 666, nil })) }() } wg.Wait()
Index ¶
- Constants
- func IsNotFound(err error) bool
- type AutoSetOption
- type Cache
- func (c *Cache) AutoGC(duration time.Duration) chan<- struct{}
- func (c *Cache) AutoSet(key string, fn func(ctx context.Context) (interface{}, error), ...) chan<- struct{}
- func (c *Cache) Delete(key string)
- func (c *Cache) DeleteAll()
- func (c *Cache) GC()
- func (c *Cache) Get(key string, opts ...GetOption) (interface{}, error)
- func (c *Cache) Set(key string, value interface{}, opts ...SetOption)
- func (c *Cache) Size() int
- type GetOption
- type Option
- type SetOption
Constants ¶
const Version = "v0.3.2"
Version is the version string representation of cachego.
Variables ¶
This section is empty.
Functions ¶
func IsNotFound ¶ added in v0.3.2
IsNotFound returns if this error is key not found.
Types ¶
type AutoSetOption ¶ added in v0.3.2
type AutoSetOption func(conf *config.AutoSetConfig)
AutoSetOption is a function which initializes AutoSetConfig.
func WithAutoSetContext ¶ added in v0.3.2
func WithAutoSetContext(ctx context.Context) AutoSetOption
WithAutoSetContext sets context to ctx.
func WithAutoSetGap ¶ added in v0.3.2
func WithAutoSetGap(gap time.Duration) AutoSetOption
WithAutoSetGap sets the gap between two set operations to gap.
func WithAutoSetNoTTL ¶ added in v0.3.2
func WithAutoSetNoTTL() AutoSetOption
WithAutoSetNoTTL sets the ttl of key to no ttl.
func WithAutoSetTTL ¶ added in v0.3.2
func WithAutoSetTTL(ttl time.Duration) AutoSetOption
WithAutoSetTTL sets the ttl of key to ttl.
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache is a struct of cache.
func (*Cache) AutoGC ¶ added in v0.3.2
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, fn func(ctx context.Context) (interface{}, error), opts ...AutoSetOption) chan<- struct{}
AutoSet starts a goroutine to execute Set() at fixed duration. It returns a channel which can be used to stop this goroutine. See AutoSetOption.
func (*Cache) Delete ¶ added in v0.3.2
Delete removes the value of key. If this key is not existed, nothing will happen.
func (*Cache) DeleteAll ¶ added in v0.3.2
func (c *Cache) DeleteAll()
DeleteAll removes all keys in cache. Notice that this method is weak-consistency.
func (*Cache) GC ¶ added in v0.3.2
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) Get ¶ added in v0.1.0
Get fetches value of key from cache first, and returns it if ok. Returns an NotFoundErr if this key is not found, and you can use IsNotFound to judge if this error is not found. Also, you can specify a function which will be called if missed, so you can load this entry to cache again. See GetOption.
type GetOption ¶ added in v0.3.2
GetOption is a function which initializes GetConfig.
func WithGetContext ¶ added in v0.3.2
WithGetContext sets context to ctx.
func WithGetDisableSingleflight ¶ added in v0.3.2
func WithGetDisableSingleflight() GetOption
WithGetDisableSingleflight sets the single-flight mode to false.
func WithGetNoTTL ¶ added in v0.3.2
func WithGetNoTTL() GetOption
WithGetNoTTL sets the ttl of missed key to no ttl.
func WithGetOnMissed ¶ added in v0.3.2
WithGetOnMissed sets onMissed to Get operation.
func WithGetTTL ¶ added in v0.3.2
WithGetTTL sets the ttl of missed key if loaded to ttl.
type Option ¶ added in v0.2.1
Option is a function which initializes Config.
func WithAutoGC ¶ added in v0.2.1
WithAutoGC is an option turning on automatically gc.
func WithDisableSingleflight ¶ added in v0.3.2
func WithDisableSingleflight() Option
WithDisableSingleflight is an option disabling single-flight mode of cache.
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. segmentSize must be the pow of 2 (such as 64) or the segments may be uneven.
type SetOption ¶ added in v0.3.2
SetOption is a function which initializes SetConfig.
func WithSetNoTTL ¶ added in v0.3.2
func WithSetNoTTL() SetOption
WithSetNoTTL sets the ttl of key to no ttl.
func WithSetTTL ¶ added in v0.3.2
WithSetTTL sets the ttl of key to ttl.