1 // Copyright (c) 2012-2016 The Revel Framework Authors, All rights reserved.
2 // Revel Framework source code and usage is governed by a MIT style
3 // license that can be found in the LICENSE file.
12 // Length of time to cache an item.
14 DefaultExpiryTime = time.Duration(0)
15 ForEverNeverExpiry = time.Duration(-1)
18 // Getter is an interface for getting / decoding an element from a cache.
19 type Getter interface {
20 // Get the content associated with the given key. decoding it into the given
24 // - nil if the value was successfully retrieved and ptrValue set
25 // - ErrCacheMiss if the value was not in the cache
26 // - an implementation specific error otherwise
27 Get(key string, ptrValue interface{}) error
30 // Cache is an interface to an expiring cache. It behaves (and is modeled) like
31 // the Memcached interface. It is keyed by strings (250 bytes at most).
33 // Many callers will make exclusive use of Set and Get, but more exotic
34 // functions are also available.
38 // Here is a typical Get/Set interaction:
41 // if err := cache.Get("items", &items); err != nil {
42 // items = loadItems()
43 // go cache.Set("items", items, cache.DefaultExpiryTime)
46 // Note that the caller will frequently not wait for Set() to complete.
50 // It is assumed that callers will infrequently check returned errors, since any
51 // request should be fulfillable without finding anything in the cache. As a
52 // result, all errors other than ErrCacheMiss and ErrNotStored will be logged to
53 // revel.ERROR, so that the developer does not need to check the return value to
54 // discover things like deserialization or connection errors.
55 type Cache interface {
56 // The Cache implements a Getter.
59 // Set the given key/value in the cache, overwriting any existing value
60 // associated with that key. Keys may be at most 250 bytes in length.
64 // - an implementation specific error otherwise
65 Set(key string, value interface{}, expires time.Duration) error
67 // Get the content associated multiple keys at once. On success, the caller
68 // may decode the values one at a time from the returned Getter.
71 // - the value getter, and a nil error if the operation completed.
72 // - an implementation specific error otherwise
73 GetMulti(keys ...string) (Getter, error)
75 // Delete the given key from the cache.
78 // - nil on a successful delete
79 // - ErrCacheMiss if the value was not in the cache
80 // - an implementation specific error otherwise
81 Delete(key string) error
83 // Add the given key/value to the cache ONLY IF the key does not already exist.
86 // - nil if the value was added to the cache
87 // - ErrNotStored if the key was already present in the cache
88 // - an implementation-specific error otherwise
89 Add(key string, value interface{}, expires time.Duration) error
91 // Set the given key/value in the cache ONLY IF the key already exists.
94 // - nil if the value was replaced
95 // - ErrNotStored if the key does not exist in the cache
96 // - an implementation specific error otherwise
97 Replace(key string, value interface{}, expires time.Duration) error
99 // Increment the value stored at the given key by the given amount.
100 // The value silently wraps around upon exceeding the uint64 range.
102 // Returns the new counter value if the operation was successful, or:
103 // - ErrCacheMiss if the key was not found in the cache
104 // - an implementation specific error otherwise
105 Increment(key string, n uint64) (newValue uint64, err error)
107 // Decrement the value stored at the given key by the given amount.
108 // The value is capped at 0 on underflow, with no error returned.
110 // Returns the new counter value if the operation was successful, or:
111 // - ErrCacheMiss if the key was not found in the cache
112 // - an implementation specific error otherwise
113 Decrement(key string, n uint64) (newValue uint64, err error)
115 // Expire all cache entries immediately.
116 // This is not implemented for the memcached cache (intentionally).
117 // Returns an implementation specific error if the operation failed.
124 ErrCacheMiss = errors.New("revel/cache: key not found")
125 ErrNotStored = errors.New("revel/cache: not stored")
126 ErrInvalidValue = errors.New("revel/cache: invalid value")
129 // The package implements the Cache interface (as sugar).
131 func Get(key string, ptrValue interface{}) error { return Instance.Get(key, ptrValue) }
132 func GetMulti(keys ...string) (Getter, error) { return Instance.GetMulti(keys...) }
133 func Delete(key string) error { return Instance.Delete(key) }
134 func Increment(key string, n uint64) (newValue uint64, err error) { return Instance.Increment(key, n) }
135 func Decrement(key string, n uint64) (newValue uint64, err error) { return Instance.Decrement(key, n) }
136 func Flush() error { return Instance.Flush() }
137 func Set(key string, value interface{}, expires time.Duration) error {
138 return Instance.Set(key, value, expires)
140 func Add(key string, value interface{}, expires time.Duration) error {
141 return Instance.Add(key, value, expires)
143 func Replace(key string, value interface{}, expires time.Duration) error {
144 return Instance.Replace(key, value, expires)