From 5b57c35522804a8282e888abb69f059c765c25f8 Mon Sep 17 00:00:00 2001 From: John Date: Fri, 27 Aug 2021 00:01:15 +0800 Subject: [PATCH] comment updates for package gcache --- os/gcache/gcache.go | 62 +++++++------- os/gcache/gcache_adapter.go | 90 ++++++++++---------- os/gcache/gcache_adapter_memory.go | 106 ++++++++++++------------ os/gcache/gcache_adapter_memory_data.go | 20 ++--- os/gcache/gcache_adapter_memory_item.go | 2 +- os/gcache/gcache_adapter_memory_lru.go | 10 +-- os/gcache/gcache_cache.go | 4 +- os/gcache/gcache_cache_adapter.go | 84 +++++++++---------- 8 files changed, 189 insertions(+), 189 deletions(-) diff --git a/os/gcache/gcache.go b/os/gcache/gcache.go index 6bfb36d48..8a0b1c07d 100644 --- a/os/gcache/gcache.go +++ b/os/gcache/gcache.go @@ -5,7 +5,7 @@ // You can obtain one at https://github.com/gogf/gf. // Package gcache provides kinds of cache management for process. -// It default provides a concurrent-safe in-memory cache adapter for process. +// It provides a concurrent-safe in-memory cache adapter for process in default. package gcache import ( @@ -23,62 +23,62 @@ func Ctx(ctx context.Context) *Cache { return defaultCache.Ctx(ctx) } -// Set sets cache with - pair, which is expired after . -// It does not expire if == 0. -func Set(key interface{}, value interface{}, duration time.Duration) { - defaultCache.Set(key, value, duration) +// Set sets cache with `key`-`value` pair, which is expired after `duration`. +// It does not expire if `duration` == 0. +func Set(key interface{}, value interface{}, duration time.Duration) error { + return defaultCache.Set(key, value, duration) } -// SetIfNotExist sets cache with - pair if does not exist in the cache, -// which is expired after . It does not expire if == 0. +// SetIfNotExist sets cache with `key`-`value` pair if `key` does not exist in the cache, +// which is expired after `duration`. It does not expire if `duration` == 0. func SetIfNotExist(key interface{}, value interface{}, duration time.Duration) (bool, error) { return defaultCache.SetIfNotExist(key, value, duration) } -// Sets batch sets cache with key-value pairs by , which is expired after . +// Sets batch sets cache with key-value pairs by `data`, which is expired after `duration`. // -// It does not expire if == 0. +// It does not expire if `duration` == 0. func Sets(data map[interface{}]interface{}, duration time.Duration) error { return defaultCache.Sets(data, duration) } -// Get returns the value of . +// Get returns the value of `key`. // It returns nil if it does not exist or its value is nil. func Get(key interface{}) (interface{}, error) { return defaultCache.Get(key) } -// GetVar retrieves and returns the value of as gvar.Var. +// GetVar retrieves and returns the value of `key` as gvar.Var. func GetVar(key interface{}) (*gvar.Var, error) { return defaultCache.GetVar(key) } -// GetOrSet returns the value of , -// or sets - pair and returns if does not exist in the cache. -// The key-value pair expires after . +// GetOrSet returns the value of `key`, +// or sets `key`-`value` pair and returns `value` if `key` does not exist in the cache. +// The key-value pair expires after `duration`. // -// It does not expire if == 0. +// It does not expire if `duration` == 0. func GetOrSet(key interface{}, value interface{}, duration time.Duration) (interface{}, error) { return defaultCache.GetOrSet(key, value, duration) } -// GetOrSetFunc returns the value of , or sets with result of function -// and returns its result if does not exist in the cache. The key-value pair expires -// after . It does not expire if == 0. +// GetOrSetFunc returns the value of `key`, or sets `key` with result of function `f` +// and returns its result if `key` does not exist in the cache. The key-value pair expires +// after `duration`. It does not expire if `duration` == 0. func GetOrSetFunc(key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) { return defaultCache.GetOrSetFunc(key, f, duration) } -// GetOrSetFuncLock returns the value of , or sets with result of function -// and returns its result if does not exist in the cache. The key-value pair expires -// after . It does not expire if == 0. +// GetOrSetFuncLock returns the value of `key`, or sets `key` with result of function `f` +// and returns its result if `key` does not exist in the cache. The key-value pair expires +// after `duration`. It does not expire if `duration` == 0. // -// Note that the function is executed within writing mutex lock. +// Note that the function `f` is executed within writing mutex lock. func GetOrSetFuncLock(key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) { return defaultCache.GetOrSetFuncLock(key, f, duration) } -// Contains returns true if exists in the cache, or else returns false. +// Contains returns true if `key` exists in the cache, or else returns false. func Contains(key interface{}) (bool, error) { return defaultCache.Contains(key) } @@ -89,10 +89,10 @@ func Remove(keys ...interface{}) (value interface{}, err error) { return defaultCache.Remove(keys...) } -// Removes deletes in the cache. +// Removes deletes `keys` in the cache. // Deprecated, use Remove instead. func Removes(keys []interface{}) { - defaultCache.Removes(keys) + defaultCache.Remove(keys...) } // Data returns a copy of all key-value pairs in the cache as map type. @@ -120,20 +120,20 @@ func Size() (int, error) { return defaultCache.Size() } -// GetExpire retrieves and returns the expiration of . -// It returns -1 if the does not exist in the cache. +// GetExpire retrieves and returns the expiration of `key`. +// It returns -1 if the `key` does not exist in the cache. func GetExpire(key interface{}) (time.Duration, error) { return defaultCache.GetExpire(key) } -// Update updates the value of without changing its expiration and returns the old value. -// The returned value is false if the does not exist in the cache. +// Update updates the value of `key` without changing its expiration and returns the old value. +// The returned `exist` value is false if the `key` does not exist in the cache. func Update(key interface{}, value interface{}) (oldValue interface{}, exist bool, err error) { return defaultCache.Update(key, value) } -// UpdateExpire updates the expiration of and returns the old expiration duration value. -// It returns -1 if the does not exist in the cache. +// UpdateExpire updates the expiration of `key` and returns the old expiration duration value. +// It returns -1 if the `key` does not exist in the cache. func UpdateExpire(key interface{}, duration time.Duration) (oldDuration time.Duration, err error) { return defaultCache.UpdateExpire(key, duration) } diff --git a/os/gcache/gcache_adapter.go b/os/gcache/gcache_adapter.go index f12c32570..33f179058 100644 --- a/os/gcache/gcache_adapter.go +++ b/os/gcache/gcache_adapter.go @@ -11,95 +11,95 @@ import ( "time" ) -// Adapter is the adapter for cache features implements. +// Adapter is the core adapter for cache features implements. type Adapter interface { - // Set sets cache with - pair, which is expired after . + // Set sets cache with `key`-`value` pair, which is expired after `duration`. // - // It does not expire if == 0. - // It deletes the if < 0. + // It does not expire if `duration` == 0. + // It deletes the `key` if `duration` < 0. Set(ctx context.Context, key interface{}, value interface{}, duration time.Duration) error - // Sets batch sets cache with key-value pairs by , which is expired after . + // Sets batch sets cache with key-value pairs by `data`, which is expired after `duration`. // - // It does not expire if == 0. - // It deletes the keys of if < 0 or given is nil. + // It does not expire if `duration` == 0. + // It deletes the keys of `data` if `duration` < 0 or given `value` is nil. Sets(ctx context.Context, data map[interface{}]interface{}, duration time.Duration) error - // SetIfNotExist sets cache with - pair which is expired after - // if does not exist in the cache. It returns true the dose not exist in the - // cache and it sets successfully to the cache, or else it returns false. + // SetIfNotExist sets cache with `key`-`value` pair which is expired after `duration` + // if `key` does not exist in the cache. It returns true the `key` does not exist in the + // cache, and it sets `value` successfully to the cache, or else it returns false. // - // The parameter can be type of , but it dose nothing if its + // The parameter `value` can be type of `func() interface{}`, but it does nothing if its // result is nil. // - // It does not expire if == 0. - // It deletes the if < 0 or given is nil. + // It does not expire if `duration` == 0. + // It deletes the `key` if `duration` < 0 or given `value` is nil. SetIfNotExist(ctx context.Context, key interface{}, value interface{}, duration time.Duration) (bool, error) - // Get retrieves and returns the associated value of given . - // It returns nil if it does not exist, its value is nil or it's expired. + // Get retrieves and returns the associated value of given `key`. + // It returns nil if it does not exist, its value is nil, or it's expired. Get(ctx context.Context, key interface{}) (interface{}, error) - // GetOrSet retrieves and returns the value of , or sets - pair and - // returns if does not exist in the cache. The key-value pair expires - // after . + // GetOrSet retrieves and returns the value of `key`, or sets `key`-`value` pair and + // returns `value` if `key` does not exist in the cache. The key-value pair expires + // after `duration`. // - // It does not expire if == 0. - // It deletes the if < 0 or given is nil, but it does nothing - // if is a function and the function result is nil. + // It does not expire if `duration` == 0. + // It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing + // if `value` is a function and the function result is nil. GetOrSet(ctx context.Context, key interface{}, value interface{}, duration time.Duration) (interface{}, error) - // GetOrSetFunc retrieves and returns the value of , or sets with result of - // function and returns its result if does not exist in the cache. The key-value - // pair expires after . + // GetOrSetFunc retrieves and returns the value of `key`, or sets `key` with result of + // function `f` and returns its result if `key` does not exist in the cache. The key-value + // pair expires after `duration`. // - // It does not expire if == 0. - // It deletes the if < 0 or given is nil, but it does nothing - // if is a function and the function result is nil. + // It does not expire if `duration` == 0. + // It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing + // if `value` is a function and the function result is nil. GetOrSetFunc(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) - // GetOrSetFuncLock retrieves and returns the value of , or sets with result of - // function and returns its result if does not exist in the cache. The key-value - // pair expires after . + // GetOrSetFuncLock retrieves and returns the value of `key`, or sets `key` with result of + // function `f` and returns its result if `key` does not exist in the cache. The key-value + // pair expires after `duration`. // - // It does not expire if == 0. - // It does nothing if function returns nil. + // It does not expire if `duration` == 0. + // It does nothing if function `f` returns nil. // - // Note that the function should be executed within writing mutex lock for concurrent + // Note that the function `f` should be executed within writing mutex lock for concurrent // safety purpose. GetOrSetFuncLock(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) - // Contains returns true if exists in the cache, or else returns false. + // Contains returns true if `key` exists in the cache, or else returns false. Contains(ctx context.Context, key interface{}) (bool, error) - // GetExpire retrieves and returns the expiration of in the cache. + // GetExpire retrieves and returns the expiration of `key` in the cache. // - // It returns 0 if the does not expire. - // It returns -1 if the does not exist in the cache. + // It returns 0 if the `key` does not expire. + // It returns -1 if the `key` does not exist in the cache. GetExpire(ctx context.Context, key interface{}) (time.Duration, error) // Remove deletes one or more keys from cache, and returns its value. // If multiple keys are given, it returns the value of the last deleted item. Remove(ctx context.Context, keys ...interface{}) (value interface{}, err error) - // Update updates the value of without changing its expiration and returns the old value. - // The returned value is false if the does not exist in the cache. + // Update updates the value of `key` without changing its expiration and returns the old value. + // The returned value `exist` is false if the `key` does not exist in the cache. // - // It deletes the if given is nil. - // It does nothing if does not exist in the cache. + // It deletes the `key` if given `value` is nil. + // It does nothing if `key` does not exist in the cache. Update(ctx context.Context, key interface{}, value interface{}) (oldValue interface{}, exist bool, err error) - // UpdateExpire updates the expiration of and returns the old expiration duration value. + // UpdateExpire updates the expiration of `key` and returns the old expiration duration value. // - // It returns -1 and does nothing if the does not exist in the cache. - // It deletes the if < 0. + // It returns -1 and does nothing if the `key` does not exist in the cache. + // It deletes the `key` if `duration` < 0. UpdateExpire(ctx context.Context, key interface{}, duration time.Duration) (oldDuration time.Duration, err error) // Size returns the number of items in the cache. Size(ctx context.Context) (size int, err error) // Data returns a copy of all key-value pairs in the cache as map type. - // Note that this function may leads lots of memory usage, you can implement this function + // Note that this function may lead lots of memory usage, you can implement this function // if necessary. Data(ctx context.Context) (map[interface{}]interface{}, error) diff --git a/os/gcache/gcache_adapter_memory.go b/os/gcache/gcache_adapter_memory.go index cc8dba5b2..c70b2b3e3 100644 --- a/os/gcache/gcache_adapter_memory.go +++ b/os/gcache/gcache_adapter_memory.go @@ -29,7 +29,7 @@ type adapterMemory struct { expireTimes *adapterMemoryExpireTimes // expireTimes is the expiring key to its timestamp mapping, which is used for quick indexing and deleting. expireSets *adapterMemoryExpireSets // expireSets is the expiring timestamp to its key set mapping, which is used for quick indexing and deleting. lru *adapterMemoryLru // lru is the LRU manager, which is enabled when attribute cap > 0. - lruGetList *glist.List // lruGetList is the LRU history according with Get function. + lruGetList *glist.List // lruGetList is the LRU history according to Get function. eventList *glist.List // eventList is the asynchronous event list for internal data synchronization. closed *gtype.Bool // closed controls the cache closed or not. } @@ -69,10 +69,10 @@ func newAdapterMemory(lruCap ...int) *adapterMemory { return c } -// Set sets cache with - pair, which is expired after . +// Set sets cache with `key`-`value` pair, which is expired after `duration`. // -// It does not expire if == 0. -// It deletes the if < 0. +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0. func (c *adapterMemory) Set(ctx context.Context, key interface{}, value interface{}, duration time.Duration) error { expireTime := c.getInternalExpire(duration) c.data.Set(key, adapterMemoryItem{ @@ -86,19 +86,19 @@ func (c *adapterMemory) Set(ctx context.Context, key interface{}, value interfac return nil } -// Update updates the value of without changing its expiration and returns the old value. -// The returned value is false if the does not exist in the cache. +// Update updates the value of `key` without changing its expiration and returns the old value. +// The returned value `exist` is false if the `key` does not exist in the cache. // -// It deletes the if given is nil. -// It does nothing if does not exist in the cache. +// It deletes the `key` if given `value` is nil. +// It does nothing if `key` does not exist in the cache. func (c *adapterMemory) Update(ctx context.Context, key interface{}, value interface{}) (oldValue interface{}, exist bool, err error) { return c.data.Update(key, value) } -// UpdateExpire updates the expiration of and returns the old expiration duration value. +// UpdateExpire updates the expiration of `key` and returns the old expiration duration value. // -// It returns -1 and does nothing if the does not exist in the cache. -// It deletes the if < 0. +// It returns -1 and does nothing if the `key` does not exist in the cache. +// It deletes the `key` if `duration` < 0. func (c *adapterMemory) UpdateExpire(ctx context.Context, key interface{}, duration time.Duration) (oldDuration time.Duration, err error) { newExpireTime := c.getInternalExpire(duration) oldDuration, err = c.data.UpdateExpire(key, newExpireTime) @@ -114,10 +114,10 @@ func (c *adapterMemory) UpdateExpire(ctx context.Context, key interface{}, durat return } -// GetExpire retrieves and returns the expiration of in the cache. +// GetExpire retrieves and returns the expiration of `key` in the cache. // -// It returns 0 if the does not expire. -// It returns -1 if the does not exist in the cache. +// It returns 0 if the `key` does not expire. +// It returns -1 if the `key` does not exist in the cache. func (c *adapterMemory) GetExpire(ctx context.Context, key interface{}) (time.Duration, error) { if item, ok := c.data.Get(key); ok { return time.Duration(item.e-gtime.TimestampMilli()) * time.Millisecond, nil @@ -125,14 +125,14 @@ func (c *adapterMemory) GetExpire(ctx context.Context, key interface{}) (time.Du return -1, nil } -// SetIfNotExist sets cache with - pair which is expired after -// if does not exist in the cache. It returns true the dose not exist in the -// cache and it sets successfully to the cache, or else it returns false. -// The parameter can be type of , but it dose nothing if its +// SetIfNotExist sets cache with `key`-`value` pair which is expired after `duration` +// if `key` does not exist in the cache. It returns true the `key` does not exist in the +// cache, and it sets `value` successfully to the cache, or else it returns false. +// The parameter `value` can be type of , but it dose nothing if its // result is nil. // -// It does not expire if == 0. -// It deletes the if < 0 or given is nil. +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil. func (c *adapterMemory) SetIfNotExist(ctx context.Context, key interface{}, value interface{}, duration time.Duration) (bool, error) { isContained, err := c.Contains(ctx, key) if err != nil { @@ -148,10 +148,10 @@ func (c *adapterMemory) SetIfNotExist(ctx context.Context, key interface{}, valu return false, nil } -// Sets batch sets cache with key-value pairs by , which is expired after . +// Sets batch sets cache with key-value pairs by `data`, which is expired after `duration`. // -// It does not expire if == 0. -// It deletes the keys of if < 0 or given is nil. +// It does not expire if `duration` == 0. +// It deletes the keys of `data` if `duration` < 0 or given `value` is nil. func (c *adapterMemory) Sets(ctx context.Context, data map[interface{}]interface{}, duration time.Duration) error { var ( expireTime = c.getInternalExpire(duration) @@ -169,7 +169,7 @@ func (c *adapterMemory) Sets(ctx context.Context, data map[interface{}]interface return nil } -// Get retrieves and returns the associated value of given . +// Get retrieves and returns the associated value of given `key`. // It returns nil if it does not exist or its value is nil. func (c *adapterMemory) Get(ctx context.Context, key interface{}) (interface{}, error) { item, ok := c.data.Get(key) @@ -183,13 +183,13 @@ func (c *adapterMemory) Get(ctx context.Context, key interface{}) (interface{}, return nil, nil } -// GetOrSet retrieves and returns the value of , or sets - pair and -// returns if does not exist in the cache. The key-value pair expires -// after . +// GetOrSet retrieves and returns the value of `key`, or sets `key`-`value` pair and +// returns `value` if `key` does not exist in the cache. The key-value pair expires +// after `duration`. // -// It does not expire if == 0. -// It deletes the if < 0 or given is nil, but it does nothing -// if is a function and the function result is nil. +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing +// if `value` is a function and the function result is nil. func (c *adapterMemory) GetOrSet(ctx context.Context, key interface{}, value interface{}, duration time.Duration) (interface{}, error) { v, err := c.Get(ctx, key) if err != nil { @@ -202,13 +202,13 @@ func (c *adapterMemory) GetOrSet(ctx context.Context, key interface{}, value int } } -// GetOrSetFunc retrieves and returns the value of , or sets with result of -// function and returns its result if does not exist in the cache. The key-value -// pair expires after . +// GetOrSetFunc retrieves and returns the value of `key`, or sets `key` with result of +// function `f` and returns its result if `key` does not exist in the cache. The key-value +// pair expires after `duration`. // -// It does not expire if == 0. -// It deletes the if < 0 or given is nil, but it does nothing -// if is a function and the function result is nil. +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing +// if `value` is a function and the function result is nil. func (c *adapterMemory) GetOrSetFunc(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) { v, err := c.Get(ctx, key) if err != nil { @@ -228,14 +228,14 @@ func (c *adapterMemory) GetOrSetFunc(ctx context.Context, key interface{}, f fun } } -// GetOrSetFuncLock retrieves and returns the value of , or sets with result of -// function and returns its result if does not exist in the cache. The key-value -// pair expires after . +// GetOrSetFuncLock retrieves and returns the value of `key`, or sets `key` with result of +// function `f` and returns its result if `key` does not exist in the cache. The key-value +// pair expires after `duration`. // -// It does not expire if == 0. -// It does nothing if function returns nil. +// It does not expire if `duration` == 0. +// It does nothing if function `f` returns nil. // -// Note that the function should be executed within writing mutex lock for concurrent +// Note that the function `f` should be executed within writing mutex lock for concurrent // safety purpose. func (c *adapterMemory) GetOrSetFuncLock(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) { v, err := c.Get(ctx, key) @@ -249,7 +249,7 @@ func (c *adapterMemory) GetOrSetFuncLock(ctx context.Context, key interface{}, f } } -// Contains returns true if exists in the cache, or else returns false. +// Contains returns true if `key` exists in the cache, or else returns false. func (c *adapterMemory) Contains(ctx context.Context, key interface{}) (bool, error) { v, err := c.Get(ctx, key) if err != nil { @@ -310,14 +310,14 @@ func (c *adapterMemory) Close(ctx context.Context) error { return nil } -// doSetWithLockCheck sets cache with - pair if does not exist in the -// cache, which is expired after . +// doSetWithLockCheck sets cache with `key`-`value` pair if `key` does not exist in the +// cache, which is expired after `duration`. // -// It does not expire if == 0. -// The parameter can be type of , but it dose nothing if the +// It does not expire if `duration` == 0. +// The parameter `value` can be type of , but it dose nothing if the // function result is nil. // -// It doubly checks the whether exists in the cache using mutex writing lock +// It doubly checks the `key` whether exists in the cache using mutex writing lock // before setting it to the cache. func (c *adapterMemory) doSetWithLockCheck(key interface{}, value interface{}, duration time.Duration) (result interface{}, err error) { expireTimestamp := c.getInternalExpire(duration) @@ -335,14 +335,14 @@ func (c *adapterMemory) getInternalExpire(duration time.Duration) int64 { } } -// makeExpireKey groups the in milliseconds to its according seconds. +// makeExpireKey groups the `expire` in milliseconds to its according seconds. func (c *adapterMemory) makeExpireKey(expire int64) int64 { return int64(math.Ceil(float64(expire/1000)+1) * 1000) } // syncEventAndClearExpired does the asynchronous task loop: // 1. Asynchronously process the data in the event list, -// and synchronize the results to the and properties. +// and synchronize the results to the `expireTimes` and `expireSets` properties. // 2. Clean up the expired key-value pair data. func (c *adapterMemory) syncEventAndClearExpired() { if c.closed.Val() { @@ -411,13 +411,13 @@ func (c *adapterMemory) syncEventAndClearExpired() { } } -// clearByKey deletes the key-value pair with given . -// The parameter specifies whether doing this deleting forcibly. +// clearByKey deletes the key-value pair with given `key`. +// The parameter `force` specifies whether doing this deleting forcibly. func (c *adapterMemory) clearByKey(key interface{}, force ...bool) { // Doubly check before really deleting it from cache. c.data.DeleteWithDoubleCheck(key, force...) - // Deleting its expire time from . + // Deleting its expire time from `expireTimes`. c.expireTimes.Delete(key) // Deleting it from LRU. diff --git a/os/gcache/gcache_adapter_memory_data.go b/os/gcache/gcache_adapter_memory_data.go index 839922e41..86b20e0fc 100644 --- a/os/gcache/gcache_adapter_memory_data.go +++ b/os/gcache/gcache_adapter_memory_data.go @@ -23,11 +23,11 @@ func newAdapterMemoryData() *adapterMemoryData { } } -// Update updates the value of without changing its expiration and returns the old value. -// The returned value is false if the does not exist in the cache. +// Update updates the value of `key` without changing its expiration and returns the old value. +// The returned value `exist` is false if the `key` does not exist in the cache. // -// It deletes the if given is nil. -// It does nothing if does not exist in the cache. +// It deletes the `key` if given `value` is nil. +// It does nothing if `key` does not exist in the cache. func (d *adapterMemoryData) Update(key interface{}, value interface{}) (oldValue interface{}, exist bool, err error) { d.mu.Lock() defer d.mu.Unlock() @@ -41,10 +41,10 @@ func (d *adapterMemoryData) Update(key interface{}, value interface{}) (oldValue return nil, false, nil } -// UpdateExpire updates the expiration of and returns the old expiration duration value. +// UpdateExpire updates the expiration of `key` and returns the old expiration duration value. // -// It returns -1 and does nothing if the does not exist in the cache. -// It deletes the if < 0. +// It returns -1 and does nothing if the `key` does not exist in the cache. +// It deletes the `key` if `duration` < 0. func (d *adapterMemoryData) UpdateExpire(key interface{}, expireTime int64) (oldDuration time.Duration, err error) { d.mu.Lock() defer d.mu.Unlock() @@ -152,10 +152,10 @@ func (d *adapterMemoryData) Set(key interface{}, value adapterMemoryItem) { d.mu.Unlock() } -// Sets batch sets cache with key-value pairs by , which is expired after . +// Sets batch sets cache with key-value pairs by `data`, which is expired after `duration`. // -// It does not expire if == 0. -// It deletes the keys of if < 0 or given is nil. +// It does not expire if `duration` == 0. +// It deletes the keys of `data` if `duration` < 0 or given `value` is nil. func (d *adapterMemoryData) Sets(data map[interface{}]interface{}, expireTime int64) error { d.mu.Lock() for k, v := range data { diff --git a/os/gcache/gcache_adapter_memory_item.go b/os/gcache/gcache_adapter_memory_item.go index 44b72a5ef..ce411be8f 100644 --- a/os/gcache/gcache_adapter_memory_item.go +++ b/os/gcache/gcache_adapter_memory_item.go @@ -10,7 +10,7 @@ import ( "github.com/gogf/gf/os/gtime" ) -// IsExpired checks whether is expired. +// IsExpired checks whether `item` is expired. func (item *adapterMemoryItem) IsExpired() bool { // Note that it should use greater than or equal judgement here // imagining that the cache time is only 1 millisecond. diff --git a/os/gcache/gcache_adapter_memory_lru.go b/os/gcache/gcache_adapter_memory_lru.go index 455ce6d7d..c2f2a64d5 100644 --- a/os/gcache/gcache_adapter_memory_lru.go +++ b/os/gcache/gcache_adapter_memory_lru.go @@ -43,7 +43,7 @@ func (lru *adapterMemoryLru) Close() { lru.closed.Set(true) } -// Remove deletes the FROM . +// Remove deletes the `key` FROM `lru`. func (lru *adapterMemoryLru) Remove(key interface{}) { if v := lru.data.Get(key); v != nil { lru.data.Remove(key) @@ -51,17 +51,17 @@ func (lru *adapterMemoryLru) Remove(key interface{}) { } } -// Size returns the size of . +// Size returns the size of `lru`. func (lru *adapterMemoryLru) Size() int { return lru.data.Size() } -// Push pushes to the tail of . +// Push pushes `key` to the tail of `lru`. func (lru *adapterMemoryLru) Push(key interface{}) { lru.rawList.PushBack(key) } -// Pop deletes and returns the key from tail of . +// Pop deletes and returns the key from tail of `lru`. func (lru *adapterMemoryLru) Pop() interface{} { if v := lru.list.PopBack(); v != nil { lru.data.Remove(v) @@ -78,7 +78,7 @@ func (lru *adapterMemoryLru) Pop() interface{} { // fmt.Println() //} -// SyncAndClear synchronizes the keys from to and +// SyncAndClear synchronizes the keys from `rawList` to `list` and `data` // using Least Recently Used algorithm. func (lru *adapterMemoryLru) SyncAndClear() { if lru.closed.Val() { diff --git a/os/gcache/gcache_cache.go b/os/gcache/gcache_cache.go index 54f5ea626..216549bd9 100644 --- a/os/gcache/gcache_cache.go +++ b/os/gcache/gcache_cache.go @@ -56,13 +56,13 @@ func (c *Cache) SetAdapter(adapter Adapter) { c.adapter = adapter } -// GetVar retrieves and returns the value of as gvar.Var. +// GetVar retrieves and returns the value of `key` as gvar.Var. func (c *Cache) GetVar(key interface{}) (*gvar.Var, error) { v, err := c.Get(key) return gvar.New(v), err } -// Removes deletes in the cache. +// Removes deletes `keys` in the cache. // Deprecated, use Remove instead. func (c *Cache) Removes(keys []interface{}) error { _, err := c.Remove(keys...) diff --git a/os/gcache/gcache_cache_adapter.go b/os/gcache/gcache_cache_adapter.go index 0f4f50852..7ad9547fe 100644 --- a/os/gcache/gcache_cache_adapter.go +++ b/os/gcache/gcache_cache_adapter.go @@ -10,85 +10,85 @@ import ( "time" ) -// Set sets cache with - pair, which is expired after . +// Set sets cache with `key`-`value` pair, which is expired after `duration`. // -// It does not expire if == 0. -// It deletes the if < 0. +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0. func (c *Cache) Set(key interface{}, value interface{}, duration time.Duration) error { return c.adapter.Set(c.getCtx(), key, value, duration) } -// Sets batch sets cache with key-value pairs by , which is expired after . +// Sets batch sets cache with key-value pairs by `data`, which is expired after `duration`. // -// It does not expire if == 0. -// It deletes the keys of if < 0 or given is nil. +// It does not expire if `duration` == 0. +// It deletes the keys of `data` if `duration` < 0 or given `value` is nil. func (c *Cache) Sets(data map[interface{}]interface{}, duration time.Duration) error { return c.adapter.Sets(c.getCtx(), data, duration) } -// SetIfNotExist sets cache with - pair which is expired after -// if does not exist in the cache. It returns true the dose not exist in the -// cache and it sets successfully to the cache, or else it returns false. +// SetIfNotExist sets cache with `key`-`value` pair which is expired after `duration` +// if `key` does not exist in the cache. It returns true the `key` dose not exist in the +// cache, and it sets `value` successfully to the cache, or else it returns false. // -// The parameter can be type of , but it dose nothing if its +// The parameter `value` can be type of , but it dose nothing if its // result is nil. // -// It does not expire if == 0. -// It deletes the if < 0 or given is nil. +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil. func (c *Cache) SetIfNotExist(key interface{}, value interface{}, duration time.Duration) (bool, error) { return c.adapter.SetIfNotExist(c.getCtx(), key, value, duration) } -// Get retrieves and returns the associated value of given . +// Get retrieves and returns the associated value of given `key`. // It returns nil if it does not exist, its value is nil or it's expired. func (c *Cache) Get(key interface{}) (interface{}, error) { return c.adapter.Get(c.getCtx(), key) } -// GetOrSet retrieves and returns the value of , or sets - pair and -// returns if does not exist in the cache. The key-value pair expires -// after . +// GetOrSet retrieves and returns the value of `key`, or sets `key`-`value` pair and +// returns `value` if `key` does not exist in the cache. The key-value pair expires +// after `duration`. // -// It does not expire if == 0. -// It deletes the if < 0 or given is nil, but it does nothing -// if is a function and the function result is nil. +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing +// if `value` is a function and the function result is nil. func (c *Cache) GetOrSet(key interface{}, value interface{}, duration time.Duration) (interface{}, error) { return c.adapter.GetOrSet(c.getCtx(), key, value, duration) } -// GetOrSetFunc retrieves and returns the value of , or sets with result of -// function and returns its result if does not exist in the cache. The key-value -// pair expires after . +// GetOrSetFunc retrieves and returns the value of `key`, or sets `key` with result of +// function `f` and returns its result if `key` does not exist in the cache. The key-value +// pair expires after `duration`. // -// It does not expire if == 0. -// It deletes the if < 0 or given is nil, but it does nothing -// if is a function and the function result is nil. +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing +// if `value` is a function and the function result is nil. func (c *Cache) GetOrSetFunc(key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) { return c.adapter.GetOrSetFunc(c.getCtx(), key, f, duration) } -// GetOrSetFuncLock retrieves and returns the value of , or sets with result of -// function and returns its result if does not exist in the cache. The key-value -// pair expires after . +// GetOrSetFuncLock retrieves and returns the value of `key`, or sets `key` with result of +// function `f` and returns its result if `key` does not exist in the cache. The key-value +// pair expires after `duration`. // -// It does not expire if == 0. -// It does nothing if function returns nil. +// It does not expire if `duration` == 0. +// It does nothing if function `f` returns nil. // -// Note that the function should be executed within writing mutex lock for concurrent +// Note that the function `f` should be executed within writing mutex lock for concurrent // safety purpose. func (c *Cache) GetOrSetFuncLock(key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) { return c.adapter.GetOrSetFuncLock(c.getCtx(), key, f, duration) } -// Contains returns true if exists in the cache, or else returns false. +// Contains returns true if `key` exists in the cache, or else returns false. func (c *Cache) Contains(key interface{}) (bool, error) { return c.adapter.Contains(c.getCtx(), key) } -// GetExpire retrieves and returns the expiration of in the cache. +// GetExpire retrieves and returns the expiration of `key` in the cache. // -// It returns 0 if the does not expire. -// It returns -1 if the does not exist in the cache. +// It returns 0 if the `key` does not expire. +// It returns -1 if the `key` does not exist in the cache. func (c *Cache) GetExpire(key interface{}) (time.Duration, error) { return c.adapter.GetExpire(c.getCtx(), key) } @@ -99,19 +99,19 @@ func (c *Cache) Remove(keys ...interface{}) (value interface{}, err error) { return c.adapter.Remove(c.getCtx(), keys...) } -// Update updates the value of without changing its expiration and returns the old value. -// The returned value is false if the does not exist in the cache. +// Update updates the value of `key` without changing its expiration and returns the old value. +// The returned value `exist` is false if the `key` does not exist in the cache. // -// It deletes the if given is nil. -// It does nothing if does not exist in the cache. +// It deletes the `key` if given `value` is nil. +// It does nothing if `key` does not exist in the cache. func (c *Cache) Update(key interface{}, value interface{}) (oldValue interface{}, exist bool, err error) { return c.adapter.Update(c.getCtx(), key, value) } -// UpdateExpire updates the expiration of and returns the old expiration duration value. +// UpdateExpire updates the expiration of `key` and returns the old expiration duration value. // -// It returns -1 and does nothing if the does not exist in the cache. -// It deletes the if < 0. +// It returns -1 and does nothing if the `key` does not exist in the cache. +// It deletes the `key` if `duration` < 0. func (c *Cache) UpdateExpire(key interface{}, duration time.Duration) (oldDuration time.Duration, err error) { return c.adapter.UpdateExpire(c.getCtx(), key, duration) }