src/foundation/api/revel/cache/cache.go

   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.
   4
   5 package cache
   6
   7 import (
   8         "errors"
   9         "time"
  10 )
  11
  12 // Length of time to cache an item.
  13 const (
  14         DefaultExpiryTime  = time.Duration(0)
  15         ForEverNeverExpiry = time.Duration(-1)
  16 )
  17
  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
  21         // pointer.
  22         //
  23         // Returns:
  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
  28 }
  29
  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).
  32 //
  33 // Many callers will make exclusive use of Set and Get, but more exotic
  34 // functions are also available.
  35 //
  36 // Example
  37 //
  38 // Here is a typical Get/Set interaction:
  39 //
  40 //   var items []*Item
  41 //   if err := cache.Get("items", &items); err != nil {
  42 //     items = loadItems()
  43 //     go cache.Set("items", items, cache.DefaultExpiryTime)
  44 //   }
  45 //
  46 // Note that the caller will frequently not wait for Set() to complete.
  47 //
  48 // Errors
  49 //
  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.
  57         Getter
  58
  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.
  61         //
  62         // Returns:
  63         //   - nil on success
  64         //   - an implementation specific error otherwise
  65         Set(key string, value interface{}, expires time.Duration) error
  66
  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.
  69         //
  70         // Returns:
  71         //   - the value getter, and a nil error if the operation completed.
  72         //   - an implementation specific error otherwise
  73         GetMulti(keys ...string) (Getter, error)
  74
  75         // Delete the given key from the cache.
  76         //
  77         // Returns:
  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
  82
  83         // Add the given key/value to the cache ONLY IF the key does not already exist.
  84         //
  85         // Returns:
  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
  90
  91         // Set the given key/value in the cache ONLY IF the key already exists.
  92         //
  93         // Returns:
  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
  98
  99         // Increment the value stored at the given key by the given amount.
 100         // The value silently wraps around upon exceeding the uint64 range.
 101         //
 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)
 106
 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.
 109         //
 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)
 114
 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.
 118         Flush() error
 119 }
 120
 121 var (
 122         Instance Cache
 123
 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")
 127 )
 128
 129 // The package implements the Cache interface (as sugar).
 130
 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)
 139 }
 140 func Add(key string, value interface{}, expires time.Duration) error {
 141         return Instance.Add(key, value, expires)
 142 }
 143 func Replace(key string, value interface{}, expires time.Duration) error {
 144         return Instance.Replace(key, value, expires)
 145 }