以下常用方法列表，文档更新可能滞后于代码新特性，更多的方法及示例请参考代码文档：https://pkg.go.dev/github.com/gogf/gf/v2/os/gcache

`Set`

说明：使用key-value键值对设置缓存，键值可以是任意类型。

格式:

Set(ctx context.Context, key interface{}, value interface{}, duration time.Duration) error

示例：将slice切片设置到键名k1的缓存中。

func ExampleCache_Set() {
	c := gcache.New()
	c.Set(ctx, "k1", g.Slice{1, 2, 3, 4, 5, 6, 7, 8, 9}, 0)
	fmt.Println(c.Get(ctx, "k1"))

	// Output:
	// [1,2,3,4,5,6,7,8,9] <nil>
}

`SetAdapter`

说明: SetAdapter更改此缓存对象的底层适配器。请注意，此设置函数不是并发安全的。
格式：
```
SetAdapter(adapter Adapter)
```

示例：可以自己根据需要实现任意缓存适配器，实现接口方法即可。

func ExampleCache_SetAdapters() { 
	c := gcache.New()
	adapter := gcache.New()
	c.SetAdapter(adapter)
	c.Set(ctx, "k1", g.Slice{1, 2, 3, 4, 5, 6, 7, 8, 9}, 0)
	fmt.Println(c.Get(ctx, "k1"))

	// Output:
	// [1,2,3,4,5,6,7,8,9] <nil>
 }

`SetIfNotExist`

说明: 当指定key的键值不存在时设置其对应的键值value并返回true，否则什么都不做并返回false。

格式:

SetIfNotExist(ctx context.Context, key interface{}, value interface{}, duration time.Duration) (ok bool, err error)

示例：通过SetIfNotExist直接判断写入，并设置过期时间。

func ExampleCache_SetIfNotExist() { 
	c := gcache.New()
	// Write when the key name does not exist, and set the expiration time to 1000 milliseconds
	k1, err := c.SetIfNotExist(ctx, "k1", "v1", 1000*time.Millisecond)
	fmt.Println(k1, err)

	// Returns false when the key name already exists
	k2, err := c.SetIfNotExist(ctx, "k1", "v2", 1000*time.Millisecond)
	fmt.Println(k2, err)

	// Print the current list of key values
	keys1, _ := c.Keys(ctx)
	fmt.Println(keys1)

	// It does not expire if `duration` == 0. It deletes the `key` if `duration` < 0 or given `value` is nil.
	c.SetIfNotExist(ctx, "k1", 0, -10000)

	// Wait 1 second for K1: V1 to expire automatically
	time.Sleep(1200 * time.Millisecond)

	// Print the current key value pair again and find that K1: V1 has expired
	keys2, _ := c.Keys(ctx)
	fmt.Println(keys2)

	// Output:
	// true <nil>
	// false <nil>
	// [k1]
	// [<nil>]
 }

`SetMap`

说明: 批量设置键值对，输入参数类型为map[interface{}]interface{}。

格式:

SetMap(ctx context.Context, data map[interface{}]interface{}, duration time.Duration) error

示例：

func ExampleCache_SetMap() { 
 	c := gcache.New()
	// map[interface{}]interface{}
	data := g.MapAnyAny{
		"k1": "v1",
		"k2": "v2",
		"k3": "v3",
	}
	c.SetMap(ctx, data, 1000*time.Millisecond)

	// Gets the specified key value
	v1, _ := c.Get(ctx, "k1")
	v2, _ := c.Get(ctx, "k2")
	v3, _ := c.Get(ctx, "k3")

	fmt.Println(v1, v2, v3)

	// Output:
	// v1 v2 v3
 }

`Size`

说明: Size返回缓存中的项数。

格式:

Size(ctx context.Context) (size int, err error)

示例：

func ExampleCache_Size() {
	c := gcache.New()

	// Add 10 elements without expiration
	for i := 0; i < 10; i++ {
		c.Set(ctx, i, i, 0)
	}

	// Size returns the number of items in the cache.
	n, _ := c.Size(ctx)
	fmt.Println(n)

	// Output:
	// 10
}

`Update`

说明: Update更新key的对应的键值，但不更改其过期时间，并返回旧值。如果缓存中不存在key，则返回的exist值为false。

格式:

Update(ctx context.Context, key interface{}, value interface{}) (oldValue *gvar.Var, exist bool, err error)

示例：通过SetMap添加多个缓存，通过Update指定key修改value。

func ExampleCache_Update() {     
	c := gcache.New()
	c.SetMap(ctx, g.MapAnyAny{"k1": "v1", "k2": "v2", "k3": "v3"}, 0)

	k1, _ := c.Get(ctx, "k1")
	fmt.Println(k1)
	k2, _ := c.Get(ctx, "k2")
	fmt.Println(k2)
	k3, _ := c.Get(ctx, "k3")
	fmt.Println(k3)

	re, exist, _ := c.Update(ctx, "k1", "v11")
	fmt.Println(re, exist)

	re1, exist1, _ := c.Update(ctx, "k4", "v44")
	fmt.Println(re1, exist1)

	kup1, _ := c.Get(ctx, "k1")
	fmt.Println(kup1)
	kup2, _ := c.Get(ctx, "k2")
	fmt.Println(kup2)
	kup3, _ := c.Get(ctx, "k3")
	fmt.Println(kup3)

	// Output:
	// v1
	// v2
	// v3
	// v1 true
	//  false
	// v11
	// v2
	// v3 
 }

`UpdateExpire`

说明: UpdateExpire更新key的过期时间并返回旧的过期时间值。如果缓存中不存在key，则返回-1。

格式:

UpdateExpire(ctx context.Context, key interface{}, duration time.Duration) (oldDuration time.Duration, err error)

示例：通过UpdateExpire更新key的过期时间并打印查看。

func ExampleCache_UpdateExpire() {     
	c := gcache.New()
	c.Set(ctx, "k1", "v1", 1000*time.Millisecond)
	expire, _ := c.GetExpire(ctx, "k1")
	fmt.Println(expire)

	c.UpdateExpire(ctx, "k1", 500*time.Millisecond)

	expire1, _ := c.GetExpire(ctx, "k1")
	fmt.Println(expire1)

	// Output:
	// 1s
	// 500ms	
}

`Values`

说明: 通过Values获取缓存中的所有值，以切片方式返回。

格式:

Values(ctx context.Context) (values []interface{}, err error)

示例：

func ExampleCache_Values() {     
	c := gcache.New()

	c.Set(ctx, "k1", g.Map{"k1": "v1", "k2": "v2"}, 0)

	// Values returns all values in the cache as slice.
	data, _ := c.Values(ctx)
	fmt.Println(data)

	// May Output:
	// [map[k1:v1 k2:v2]]
}

`Close`

说明: 关闭缓存，让GC回收资源，默认情况下可不关闭。
格式:
```
Close(ctx context.Context) error
```

示例：通过Close即可关闭缓存。

func ExampleCache_Close() {     
 	c := gcache.New()

	c.Set(ctx, "k1", "v", 0)
	data, _ := c.Get(ctx, "k1")
	fmt.Println(data)

	// Close closes the cache if necessary.
	c.Close(ctx)

	data1, _ := c.Get(ctx, "k1")

	fmt.Println(data1)

 	// Output:
	// v
	// v
}

`Contains`

说明: 如果缓存中存在指定的key，则Contains返回true，否则返回false。

格式:

Contains(ctx context.Context, key interface{}) (bool, error)

示例：

func ExampleCache_Contains() {     
 	c := gcache.New()

	// Set Cache
	c.Set(ctx, "k", "v", 0)

	data, _ := c.Contains(ctx, "k")
	fmt.Println(data)

	// return false
	data1, _ := c.Contains(ctx, "k1")
	fmt.Println(data1)
	
 	// Output:
	// true
	// false
}

`Data`

说明: 数据以map类型返回缓存中所有键值对('key':'value')的拷贝。

格式:

Data(ctx context.Context) (data map[interface{}]interface{}, err error)

示例：获取所有缓存数据以map[interface{}]interface{}返回

func ExampleCache_Data() {     
  	c := gcache.New()

	c.SetMap(ctx, g.MapAnyAny{"k1": "v1"}, 0)
	//c.Set(ctx, "k5", "v5", 0)

	data, _ := c.Data(ctx)
	fmt.Println(data)

 	// Output:
	// map[k1:v1]
}

`Get`

说明: Get检索并返回给定key的关联值。如果它不存在、值为零或已过期，则返回nil。

格式:

Get(ctx context.Context, key interface{}) (*gvar.Var, error)

示例：

func ExampleCache_Get() {     
   	c := gcache.New()

	// Set Cache Object
	c.Set(ctx, "k1", "v1", 0)

	data, _ := c.Get(ctx, "k1")
	fmt.Println(data)
 	// Output:
	// v1
}

`GetExpire`

说明: GetExpire检索并返回缓存中key的过期时间。注意，如果key为永不过期，则返回0。如果缓存中不存在key，则返回-1。

格式:

GetExpire(ctx context.Context, key interface{}) (time.Duration, error)

示例：

func ExampleCache_GetExpire() {     
    c := gcache.New()

	// Set cache without expiration
	c.Set(ctx, "k", "v", 10000*time.Millisecond)

	expire, _ := c.GetExpire(ctx, "k")
	fmt.Println(expire)
	
 	// Output:
	// 10s
}

`GetOrSet`

说明: 检索并返回key的值，或者设置key-value对，如果缓存中不存在key，则直接设置。

格式:

GetOrSet(ctx context.Context, key interface{}, value interface{}, duration time.Duration) (result *gvar.Var, err error)

示例：用GetOrSet判断key不存在则直接设置，并设置duration时间。

func ExampleCache_GetOrSet() {     
    c := gcache.New()

	data, _ := c.GetOrSet(ctx, "k", "v", 10000*time.Millisecond)
	fmt.Println(data)

	data1, _ := c.Get(ctx, "k")
	fmt.Println(data1)

	// Output:
	// v
	// v
}

`GetOrSetFunc`

说明: 检索并返回key的值，如果key对应的值不存在则使用函数func的结果设置key，如果缓存中存在key，则返回其结果。

格式:

GetOrSetFunc(ctx context.Context, key interface{}, f func(ctx context.Context) (interface{}, error), duration time.Duration) (result *gvar.Var, err error)

示例：k1的设置返回func执行结果，k2返回nil则不执行任何操作。

func ExampleCache_GetOrSetFunc() {     
    c := gcache.New()   

	c.GetOrSetFunc(ctx, "k1", func(ctx context.Context) (value interface{}, err error) {
		return "v1", nil
	}, 10000*time.Millisecond)
	v, _ := c.Get(ctx, "k1")
	fmt.Println(v)

	c.GetOrSetFunc(ctx, "k2", func(ctx context.Context) (value interface{}, err error) {
		return nil, nil
	}, 10000*time.Millisecond)
	v1, _ := c.Get(ctx, "k2")
	fmt.Println(v1)

	// Output:
	// v1 
}

`GetOrSetFuncLock`

说明: 与GetOrSetFunc一致，但是不能重复或者覆盖注册缓存。

格式:

GetOrSetFuncLock(ctx context.Context, key interface{}, f func(ctx context.Context) (interface{}, error), duration time.Duration) (result *gvar.Var, err error)

示例：第1次的设置返回func执行结果，第2次设置操作则失效。

func ExampleCache_GetOrSetFuncLock() {     
    c := gcache.New()   

	c.GetOrSetFuncLock(ctx, "k1", func(ctx context.Context) (value interface{}, err error) {
		return "v1", nil
	}, 0)
	v, _ := c.Get(ctx, "k1")
	fmt.Println(v)

	c.GetOrSetFuncLock(ctx, "k1", func(ctx context.Context) (value interface{}, err error) {
		return "update v1", nil
	}, 0)
	v, _ = c.Get(ctx, "k1")
	fmt.Println(v)

	c.Remove(ctx, g.Slice{"k1"}...)

	// Output:
	// v1
	// v1 
}

`Keys`

说明: 缓存中所有的key所有键名并以切片格式(Slice)返回。

格式:

Keys(ctx context.Context) (keys []interface{}, err error)

示例：

func ExampleCache_Keys() {     
    c := gcache.New()

	c.SetMap(ctx, g.MapAnyAny{"k1": "v1"}, 0)

	// Print the current list of key values
	keys1, _ := c.Keys(ctx)
	fmt.Println(keys1)

	// Output:
	// [k1]
}

`KeyStrings`

说明: KeyStrings以字符串切片的形式返回缓存中的所有键。

格式:

func (c *Cache) KeyStrings(ctx context.Context) ([]string, error) {
	keys, err := c.Keys(ctx)
	if err != nil {
		return nil, err
	}
	return gconv.Strings(keys), nil
}

示例：

func ExampleCache_KeyStrings() {
	c := gcache.New()

	c.SetMap(ctx, g.MapAnyAny{"k1": "v1", "k2": "v2"}, 0)

	// KeyStrings returns all keys in the cache as string slice.
	keys,_ := c.KeyStrings(ctx)
	fmt.Println(keys)

	// May Output:
	// [k1 k2]
}

`Remove`

说明: 移除从缓存中删除一个或多个键，并返回最后一个删除的键值。

格式:

Remove(ctx context.Context, keys ...interface{}) (lastValue *gvar.Var, err error)

示例：

func ExampleCache_Remove() {     
    c := gcache.New()

	c.SetMap(ctx, g.MapAnyAny{"k1": "v1", "k2": "v2"}, 0)

	c.Remove(ctx, "k1")

	data, _ := c.Data(ctx)
	fmt.Println(data)

	// Output:
	// map[k2:v2]
}

`Removes`

说明: 从缓存中删除多个键。

格式:

func (c *Cache) Removes(ctx context.Context, keys []interface{}) error {
	_, err := c.Remove(ctx, keys...)
	return err
}

示例：

func ExampleCache_Removes() {     
    c := gcache.New()

	c.SetMap(ctx, g.MapAnyAny{"k1": "v1", "k2": "v2", "k3": "v3", "k4": "v4"}, 0)

	c.Removes(ctx, g.Slice{"k1", "k2", "k3"})

	data, _ := c.Data(ctx)
	fmt.Println(data)

	// Output:
	// map[k4:v4]
}

`MustGet`

说明: MustGet检索并返回给定key的关联值。如果它不存在、值为零或已过期，则返回nil 如果err返回不为空则会panic(err)。

格式:

func (c *Cache) MustGet(ctx context.Context, key interface{}) *gvar.Var {
	v, err := c.Get(ctx, key)
	if err != nil {
		panic(err)
	}
	return v
}

示例：

func ExampleCache_MustGet() {         
 	c := gcache.New()		
	
 	c.Set(ctx, "k1", "v1", 0)
 	k2 := c.MustGet(ctx, "k2")
	
 	k1 := c.MustGet(ctx, "k1")
	fmt.Println(k1)

	fmt.Println(k2)

 	// Output:
	// v1
	//
}

`MustGetOrSet`

说明: 检索并返回key的值，或者设置key-value对，如果缓存中不存在key，则直接设置。如果err返回不为空则会panic(err)。

格式:

func (c *Cache) MustGetOrSet(ctx context.Context, key interface{}, value interface{}, duration time.Duration) *gvar.Var {
	v, err := c.GetOrSet(ctx, key, value, duration)
	if err != nil {
		panic(err)
	}
	return v
}

示例：

func ExampleCache_MustGetOrSet() {

	// Create a cache object,
	// Of course, you can also easily use the gcache package method directly
	c := gcache.New()

	// MustGetOrSet acts like GetOrSet, but it panics if any error occurs.
	k1 := c.MustGetOrSet(ctx, "k1", "v1", 0)
	fmt.Println(k1)

	k2 := c.MustGetOrSet(ctx, "k1", "v2", 0)
	fmt.Println(k2)

	// Output:
	// v1
	// v1

}

`MustGetOrSetFunc`

说明: 检索并返回key的值，如果key对应的值不存在则使用函数func的结果设置key，如果缓存中存在key，则返回其结果。如果err返回不为空则会panic(err)。

格式:

func (c *Cache) MustGetOrSetFunc(ctx context.Context, key interface{}, f func(ctx context.Context) (interface{}, error), duration time.Duration) *gvar.Var {
	v, err := c.GetOrSetFunc(ctx, key, f, duration)
	if err != nil {
		panic(err)
	}
	return v
}

示例：

func ExampleCache_MustGetOrSetFunc() {
	c := gcache.New()

	c.MustGetOrSetFunc(ctx, 1, func(ctx context.Context) (interface{}, error) {
		return 111, nil
	}, 10000*time.Millisecond)
	v := c.MustGet(ctx, 1)
	fmt.Println(v)

	c.MustGetOrSetFunc(ctx, 2, func(ctx context.Context) (interface{}, error) {
		return nil, nil
	}, 10000*time.Millisecond)
	v1 := c.MustGet(ctx, 2)
	fmt.Println(v1)

	// Output:
	// 111
	//
}

`MustGetOrSetFuncLock`

说明: 与MustGetOrSetFunc一致，但是不能重复或者覆盖注册缓存。如果err返回不为空则会panic(err)。

格式:

func (c *Cache) MustGetOrSetFuncLock(ctx context.Context, key interface{}, f func(ctx context.Context) (interface{}, error), duration time.Duration) *gvar.Var {
	v, err := c.GetOrSetFuncLock(ctx, key, f, duration)
	if err != nil {
		panic(err)
	}
	return v
}

示例：

func ExampleCache_MustGetOrSetFuncLock() {
	c := gcache.New()

	c.MustGetOrSetFuncLock(ctx, "k1", func(ctx context.Context) (interface{}, error) {
		return "v1", nil
	}, 0)
	v := c.MustGet(ctx, "k1")
	fmt.Println(v)

	// Modification failed
	c.MustGetOrSetFuncLock(ctx, "k1", func(ctx context.Context) (interface{}, error) {
		return "update v1", nil
	}, 0)
	v = c.MustGet(ctx, "k1")
	fmt.Println(v)

	// Output:
	// v1
	// v1
}

`MustContains`

说明: 如果缓存中存在指定的key，则Contains返回true，否则返回false。如果err返回不为空则会panic(err)。

格式:

func (c *Cache) MustContains(ctx context.Context, key interface{}) bool {
	v, err := c.Contains(ctx, key)
	if err != nil {
		panic(err)
	}
	return v
}

示例：

func ExampleCache_MustContains() {
	c := gcache.New()

	// Set Cache
	c.Set(ctx, "k", "v", 0)

	// Contains returns true if `key` exists in the cache, or else returns false.
	// return true
	data := c.MustContains(ctx, "k")
	fmt.Println(data)

	// return false
	data1 := c.MustContains(ctx, "k1")
	fmt.Println(data1)

	// Output:
	// true
	// false

}

`MustGetExpire`

说明: MustGetExpire检索并返回缓存中key的过期时间。注意，如果key为永不过期，则返回0。如果缓存中不存在key，则返回-1，如果err返回不为空则会panic(err)。

格式:

func (c *Cache) MustGetExpire(ctx context.Context, key interface{}) time.Duration {
	v, err := c.GetExpire(ctx, key)
	if err != nil {
		panic(err)
	}
	return v
}

示例：

func ExampleCache_MustGetExpire() {
	c := gcache.New()

	// Set cache without expiration
	c.Set(ctx, "k", "v", 10000*time.Millisecond)

	// MustGetExpire acts like GetExpire, but it panics if any error occurs.
	expire := c.MustGetExpire(ctx, "k")
	fmt.Println(expire)

	// May Output:
	// 10s
}

`MustSize`

说明: MustSize返回缓存中的项数。如果err返回不为空则会panic(err)。

格式:

func (c *Cache) MustSize(ctx context.Context) int {
	v, err := c.Size(ctx)
	if err != nil {
		panic(err)
	}
	return v
}

示例：

func ExampleCache_MustSize() {
	c := gcache.New()

	// Add 10 elements without expiration
	for i := 0; i < 10; i++ {
		c.Set(ctx, i, i, 0)
	}

	// Size returns the number of items in the cache.
	n := c.MustSize(ctx)
	fmt.Println(n)

	// Output:
	// 10
}

`MustData`

说明: 数据以map类型返回缓存中所有键值对('key':'value')的拷贝。如果err返回不为空则会panic(err)。

格式:

func (c *Cache) MustData(ctx context.Context) map[interface{}]interface{} {
	v, err := c.Data(ctx)
	if err != nil {
		panic(err)
	}
	return v
}

示例：

func ExampleCache_MustData() {
	c := gcache.New()

	c.SetMap(ctx, g.MapAnyAny{"k1": "v1"}, 0)

	data := c.MustData(ctx)
	fmt.Println(data)

	// Set Cache
	c.Set(ctx, "k5", "v5", 0)
	data1, _ := c.Get(ctx, "k1")
	fmt.Println(data1)

	// Output:
	// map[k1:v1]
	// v1
}

`MustKeys`

说明: MustKeys以(slice)切片的形式返回缓存中的所有键，如果err返回不为空则会panic(err)。

格式:

func (c *Cache) MustKeys(ctx context.Context) []interface{} {
	v, err := c.Keys(ctx)
	if err != nil {
		panic(err)
	}
	return v
}

示例：

func ExampleCache_MustKeys() {
	c := gcache.New()

	c.SetMap(ctx, g.MapAnyAny{"k1": "v1", "k2": "v2"}, 0)

	// MustKeys acts like Keys, but it panics if any error occurs.
	keys1 := c.MustKeys(ctx)
	fmt.Println(keys1)

	// May Output:
	// [k1 k2]

}

`MustKeyStrings`

说明: MustKeyStrings以字符串(slice)切片的形式返回缓存中的所有键。如果err返回不为空则会panic(err)。

格式:

func (c *Cache) MustKeyStrings(ctx context.Context) []string {
	v, err := c.KeyStrings(ctx)
	if err != nil {
		panic(err)
	}
	return v
}

示例：

func ExampleCache_MustKeyStrings() {
	c := gcache.New()

	c.SetMap(ctx, g.MapAnyAny{"k1": "v1", "k2": "v2"}, 0)

	// MustKeyStrings returns all keys in the cache as string slice.
	// MustKeyStrings acts like KeyStrings, but it panics if any error occurs.
	keys := c.MustKeyStrings(ctx)
	fmt.Println(keys)

	// May Output:
	// [k1 k2]
}

`MustValues`

说明: MustValues以(slice)切片的形式返回缓存中的所有值，如果err返回不为空则会panic(err)。

格式:

func (c *Cache) MustValues(ctx context.Context) []interface{} {
	v, err := c.Values(ctx)
	if err != nil {
		panic(err)
	}
	return v
}

示例：

func ExampleCache_MustValues() {
	c := gcache.New()

	// Write value
	c.Set(ctx, "k1", "v1", 0)

	// Values returns all values in the cache as slice.
	data := c.MustValues(ctx)
	fmt.Println(data)

	// Output:
	// [v1]
}

Content Menu

Space shortcuts

Page tree

`Set`

`SetAdapter`

`SetIfNotExist`

`SetMap`

`Size`

`Update`

`UpdateExpire`

`Values`

`Close`

`Contains`

`Data`

`Get`

`GetExpire`

`GetOrSet`

`GetOrSetFunc`

`GetOrSetFuncLock`

`Keys`

`KeyStrings`

`Remove`

`Removes`

`MustGet`

`MustGetOrSet`

`MustGetOrSetFunc`

`MustGetOrSetFuncLock`

`MustContains`

`MustGetExpire`

`MustSize`

`MustData`

`MustKeys`

`MustKeyStrings`

`MustValues`

Space shortcuts

Page tree

缓存管理-方法介绍

Set

SetAdapter

SetIfNotExist

SetMap

Size

Update

UpdateExpire

Values

Close

Contains

Data

Get

GetExpire

GetOrSet

GetOrSetFunc

GetOrSetFuncLock

Keys

KeyStrings

Remove

Removes

MustGet

MustGetOrSet

MustGetOrSetFunc

MustGetOrSetFuncLock

MustContains

MustGetExpire

MustSize

MustData

MustKeys

MustKeyStrings

MustValues

`Set`

`SetAdapter`

`SetIfNotExist`

`SetMap`

`Size`

`Update`

`UpdateExpire`

`Values`

`Close`

`Contains`

`Data`

`Get`

`GetExpire`

`GetOrSet`

`GetOrSetFunc`

`GetOrSetFuncLock`

`Keys`

`KeyStrings`

`Remove`

`Removes`

`MustGet`

`MustGetOrSet`

`MustGetOrSetFunc`

`MustGetOrSetFuncLock`

`MustContains`

`MustGetExpire`

`MustSize`

`MustData`

`MustKeys`

`MustKeyStrings`

`MustValues`