cache.go

Documentation: github.com/patrickmn/go-cache

     1  package cache
     2  
     3  import (
     4  	"encoding/gob"
     5  	"fmt"
     6  	"io"
     7  	"os"
     8  	"runtime"
     9  	"sync"
    10  	"time"
    11  )
    12  
    13  type Item struct {
    14  	Object     interface{}
    15  	Expiration int64
    16  }
    17  
    18  // Returns true if the item has expired.
    19  func (item Item) Expired() bool {
    20  	if item.Expiration == 0 {
    21  		return false
    22  	}
    23  	return time.Now().UnixNano() > item.Expiration
    24  }
    25  
    26  const (
    27  	// For use with functions that take an expiration time.
    28  	NoExpiration time.Duration = -1
    29  	// For use with functions that take an expiration time. Equivalent to
    30  	// passing in the same expiration duration as was given to New() or
    31  	// NewFrom() when the cache was created (e.g. 5 minutes.)
    32  	DefaultExpiration time.Duration = 0
    33  )
    34  
    35  type Cache struct {
    36  	*cache
    37  	// If this is confusing, see the comment at the bottom of New()
    38  }
    39  
    40  type cache struct {
    41  	defaultExpiration time.Duration
    42  	items             map[string]Item
    43  	mu                sync.RWMutex
    44  	onEvicted         func(string, interface{})
    45  	janitor           *janitor
    46  }
    47  
    48  // Add an item to the cache, replacing any existing item. If the duration is 0
    49  // (DefaultExpiration), the cache's default expiration time is used. If it is -1
    50  // (NoExpiration), the item never expires.
    51  func (c *cache) Set(k string, x interface{}, d time.Duration) {
    52  	// "Inlining" of set
    53  	var e int64
    54  	if d == DefaultExpiration {
    55  		d = c.defaultExpiration
    56  	}
    57  	if d > 0 {
    58  		e = time.Now().Add(d).UnixNano()
    59  	}
    60  	c.mu.Lock()
    61  	c.items[k] = Item{
    62  		Object:     x,
    63  		Expiration: e,
    64  	}
    65  	// TODO: Calls to mu.Unlock are currently not deferred because defer
    66  	// adds ~200 ns (as of go1.)
    67  	c.mu.Unlock()
    68  }
    69  
    70  func (c *cache) set(k string, x interface{}, d time.Duration) {
    71  	var e int64
    72  	if d == DefaultExpiration {
    73  		d = c.defaultExpiration
    74  	}
    75  	if d > 0 {
    76  		e = time.Now().Add(d).UnixNano()
    77  	}
    78  	c.items[k] = Item{
    79  		Object:     x,
    80  		Expiration: e,
    81  	}
    82  }
    83  
    84  // Add an item to the cache, replacing any existing item, using the default
    85  // expiration.
    86  func (c *cache) SetDefault(k string, x interface{}) {
    87  	c.Set(k, x, DefaultExpiration)
    88  }
    89  
    90  // Add an item to the cache only if an item doesn't already exist for the given
    91  // key, or if the existing item has expired. Returns an error otherwise.
    92  func (c *cache) Add(k string, x interface{}, d time.Duration) error {
    93  	c.mu.Lock()
    94  	_, found := c.get(k)
    95  	if found {
    96  		c.mu.Unlock()
    97  		return fmt.Errorf("Item %s already exists", k)
    98  	}
    99  	c.set(k, x, d)
   100  	c.mu.Unlock()
   101  	return nil
   102  }
   103  
   104  // Set a new value for the cache key only if it already exists, and the existing
   105  // item hasn't expired. Returns an error otherwise.
   106  func (c *cache) Replace(k string, x interface{}, d time.Duration) error {
   107  	c.mu.Lock()
   108  	_, found := c.get(k)
   109  	if !found {
   110  		c.mu.Unlock()
   111  		return fmt.Errorf("Item %s doesn't exist", k)
   112  	}
   113  	c.set(k, x, d)
   114  	c.mu.Unlock()
   115  	return nil
   116  }
   117  
   118  // Get an item from the cache. Returns the item or nil, and a bool indicating
   119  // whether the key was found.
   120  func (c *cache) Get(k string) (interface{}, bool) {
   121  	c.mu.RLock()
   122  	// "Inlining" of get and Expired
   123  	item, found := c.items[k]
   124  	if !found {
   125  		c.mu.RUnlock()
   126  		return nil, false
   127  	}
   128  	if item.Expiration > 0 {
   129  		if time.Now().UnixNano() > item.Expiration {
   130  			c.mu.RUnlock()
   131  			return nil, false
   132  		}
   133  	}
   134  	c.mu.RUnlock()
   135  	return item.Object, true
   136  }
   137  
   138  // GetWithExpiration returns an item and its expiration time from the cache.
   139  // It returns the item or nil, the expiration time if one is set (if the item
   140  // never expires a zero value for time.Time is returned), and a bool indicating
   141  // whether the key was found.
   142  func (c *cache) GetWithExpiration(k string) (interface{}, time.Time, bool) {
   143  	c.mu.RLock()
   144  	// "Inlining" of get and Expired
   145  	item, found := c.items[k]
   146  	if !found {
   147  		c.mu.RUnlock()
   148  		return nil, time.Time{}, false
   149  	}
   150  
   151  	if item.Expiration > 0 {
   152  		if time.Now().UnixNano() > item.Expiration {
   153  			c.mu.RUnlock()
   154  			return nil, time.Time{}, false
   155  		}
   156  
   157  		// Return the item and the expiration time
   158  		c.mu.RUnlock()
   159  		return item.Object, time.Unix(0, item.Expiration), true
   160  	}
   161  
   162  	// If expiration <= 0 (i.e. no expiration time set) then return the item
   163  	// and a zeroed time.Time
   164  	c.mu.RUnlock()
   165  	return item.Object, time.Time{}, true
   166  }
   167  
   168  func (c *cache) get(k string) (interface{}, bool) {
   169  	item, found := c.items[k]
   170  	if !found {
   171  		return nil, false
   172  	}
   173  	// "Inlining" of Expired
   174  	if item.Expiration > 0 {
   175  		if time.Now().UnixNano() > item.Expiration {
   176  			return nil, false
   177  		}
   178  	}
   179  	return item.Object, true
   180  }
   181  
   182  // Increment an item of type int, int8, int16, int32, int64, uintptr, uint,
   183  // uint8, uint32, or uint64, float32 or float64 by n. Returns an error if the
   184  // item's value is not an integer, if it was not found, or if it is not
   185  // possible to increment it by n. To retrieve the incremented value, use one
   186  // of the specialized methods, e.g. IncrementInt64.
   187  func (c *cache) Increment(k string, n int64) error {
   188  	c.mu.Lock()
   189  	v, found := c.items[k]
   190  	if !found || v.Expired() {
   191  		c.mu.Unlock()
   192  		return fmt.Errorf("Item %s not found", k)
   193  	}
   194  	switch v.Object.(type) {
   195  	case int:
   196  		v.Object = v.Object.(int) + int(n)
   197  	case int8:
   198  		v.Object = v.Object.(int8) + int8(n)
   199  	case int16:
   200  		v.Object = v.Object.(int16) + int16(n)
   201  	case int32:
   202  		v.Object = v.Object.(int32) + int32(n)
   203  	case int64:
   204  		v.Object = v.Object.(int64) + n
   205  	case uint:
   206  		v.Object = v.Object.(uint) + uint(n)
   207  	case uintptr:
   208  		v.Object = v.Object.(uintptr) + uintptr(n)
   209  	case uint8:
   210  		v.Object = v.Object.(uint8) + uint8(n)
   211  	case uint16:
   212  		v.Object = v.Object.(uint16) + uint16(n)
   213  	case uint32:
   214  		v.Object = v.Object.(uint32) + uint32(n)
   215  	case uint64:
   216  		v.Object = v.Object.(uint64) + uint64(n)
   217  	case float32:
   218  		v.Object = v.Object.(float32) + float32(n)
   219  	case float64:
   220  		v.Object = v.Object.(float64) + float64(n)
   221  	default:
   222  		c.mu.Unlock()
   223  		return fmt.Errorf("The value for %s is not an integer", k)
   224  	}
   225  	c.items[k] = v
   226  	c.mu.Unlock()
   227  	return nil
   228  }
   229  
   230  // Increment an item of type float32 or float64 by n. Returns an error if the
   231  // item's value is not floating point, if it was not found, or if it is not
   232  // possible to increment it by n. Pass a negative number to decrement the
   233  // value. To retrieve the incremented value, use one of the specialized methods,
   234  // e.g. IncrementFloat64.
   235  func (c *cache) IncrementFloat(k string, n float64) error {
   236  	c.mu.Lock()
   237  	v, found := c.items[k]
   238  	if !found || v.Expired() {
   239  		c.mu.Unlock()
   240  		return fmt.Errorf("Item %s not found", k)
   241  	}
   242  	switch v.Object.(type) {
   243  	case float32:
   244  		v.Object = v.Object.(float32) + float32(n)
   245  	case float64:
   246  		v.Object = v.Object.(float64) + n
   247  	default:
   248  		c.mu.Unlock()
   249  		return fmt.Errorf("The value for %s does not have type float32 or float64", k)
   250  	}
   251  	c.items[k] = v
   252  	c.mu.Unlock()
   253  	return nil
   254  }
   255  
   256  // Increment an item of type int by n. Returns an error if the item's value is
   257  // not an int, or if it was not found. If there is no error, the incremented
   258  // value is returned.
   259  func (c *cache) IncrementInt(k string, n int) (int, error) {
   260  	c.mu.Lock()
   261  	v, found := c.items[k]
   262  	if !found || v.Expired() {
   263  		c.mu.Unlock()
   264  		return 0, fmt.Errorf("Item %s not found", k)
   265  	}
   266  	rv, ok := v.Object.(int)
   267  	if !ok {
   268  		c.mu.Unlock()
   269  		return 0, fmt.Errorf("The value for %s is not an int", k)
   270  	}
   271  	nv := rv + n
   272  	v.Object = nv
   273  	c.items[k] = v
   274  	c.mu.Unlock()
   275  	return nv, nil
   276  }
   277  
   278  // Increment an item of type int8 by n. Returns an error if the item's value is
   279  // not an int8, or if it was not found. If there is no error, the incremented
   280  // value is returned.
   281  func (c *cache) IncrementInt8(k string, n int8) (int8, error) {
   282  	c.mu.Lock()
   283  	v, found := c.items[k]
   284  	if !found || v.Expired() {
   285  		c.mu.Unlock()
   286  		return 0, fmt.Errorf("Item %s not found", k)
   287  	}
   288  	rv, ok := v.Object.(int8)
   289  	if !ok {
   290  		c.mu.Unlock()
   291  		return 0, fmt.Errorf("The value for %s is not an int8", k)
   292  	}
   293  	nv := rv + n
   294  	v.Object = nv
   295  	c.items[k] = v
   296  	c.mu.Unlock()
   297  	return nv, nil
   298  }
   299  
   300  // Increment an item of type int16 by n. Returns an error if the item's value is
   301  // not an int16, or if it was not found. If there is no error, the incremented
   302  // value is returned.
   303  func (c *cache) IncrementInt16(k string, n int16) (int16, error) {
   304  	c.mu.Lock()
   305  	v, found := c.items[k]
   306  	if !found || v.Expired() {
   307  		c.mu.Unlock()
   308  		return 0, fmt.Errorf("Item %s not found", k)
   309  	}
   310  	rv, ok := v.Object.(int16)
   311  	if !ok {
   312  		c.mu.Unlock()
   313  		return 0, fmt.Errorf("The value for %s is not an int16", k)
   314  	}
   315  	nv := rv + n
   316  	v.Object = nv
   317  	c.items[k] = v
   318  	c.mu.Unlock()
   319  	return nv, nil
   320  }
   321  
   322  // Increment an item of type int32 by n. Returns an error if the item's value is
   323  // not an int32, or if it was not found. If there is no error, the incremented
   324  // value is returned.
   325  func (c *cache) IncrementInt32(k string, n int32) (int32, error) {
   326  	c.mu.Lock()
   327  	v, found := c.items[k]
   328  	if !found || v.Expired() {
   329  		c.mu.Unlock()
   330  		return 0, fmt.Errorf("Item %s not found", k)
   331  	}
   332  	rv, ok := v.Object.(int32)
   333  	if !ok {
   334  		c.mu.Unlock()
   335  		return 0, fmt.Errorf("The value for %s is not an int32", k)
   336  	}
   337  	nv := rv + n
   338  	v.Object = nv
   339  	c.items[k] = v
   340  	c.mu.Unlock()
   341  	return nv, nil
   342  }
   343  
   344  // Increment an item of type int64 by n. Returns an error if the item's value is
   345  // not an int64, or if it was not found. If there is no error, the incremented
   346  // value is returned.
   347  func (c *cache) IncrementInt64(k string, n int64) (int64, error) {
   348  	c.mu.Lock()
   349  	v, found := c.items[k]
   350  	if !found || v.Expired() {
   351  		c.mu.Unlock()
   352  		return 0, fmt.Errorf("Item %s not found", k)
   353  	}
   354  	rv, ok := v.Object.(int64)
   355  	if !ok {
   356  		c.mu.Unlock()
   357  		return 0, fmt.Errorf("The value for %s is not an int64", k)
   358  	}
   359  	nv := rv + n
   360  	v.Object = nv
   361  	c.items[k] = v
   362  	c.mu.Unlock()
   363  	return nv, nil
   364  }
   365  
   366  // Increment an item of type uint by n. Returns an error if the item's value is
   367  // not an uint, or if it was not found. If there is no error, the incremented
   368  // value is returned.
   369  func (c *cache) IncrementUint(k string, n uint) (uint, error) {
   370  	c.mu.Lock()
   371  	v, found := c.items[k]
   372  	if !found || v.Expired() {
   373  		c.mu.Unlock()
   374  		return 0, fmt.Errorf("Item %s not found", k)
   375  	}
   376  	rv, ok := v.Object.(uint)
   377  	if !ok {
   378  		c.mu.Unlock()
   379  		return 0, fmt.Errorf("The value for %s is not an uint", k)
   380  	}
   381  	nv := rv + n
   382  	v.Object = nv
   383  	c.items[k] = v
   384  	c.mu.Unlock()
   385  	return nv, nil
   386  }
   387  
   388  // Increment an item of type uintptr by n. Returns an error if the item's value
   389  // is not an uintptr, or if it was not found. If there is no error, the
   390  // incremented value is returned.
   391  func (c *cache) IncrementUintptr(k string, n uintptr) (uintptr, error) {
   392  	c.mu.Lock()
   393  	v, found := c.items[k]
   394  	if !found || v.Expired() {
   395  		c.mu.Unlock()
   396  		return 0, fmt.Errorf("Item %s not found", k)
   397  	}
   398  	rv, ok := v.Object.(uintptr)
   399  	if !ok {
   400  		c.mu.Unlock()
   401  		return 0, fmt.Errorf("The value for %s is not an uintptr", k)
   402  	}
   403  	nv := rv + n
   404  	v.Object = nv
   405  	c.items[k] = v
   406  	c.mu.Unlock()
   407  	return nv, nil
   408  }
   409  
   410  // Increment an item of type uint8 by n. Returns an error if the item's value
   411  // is not an uint8, or if it was not found. If there is no error, the
   412  // incremented value is returned.
   413  func (c *cache) IncrementUint8(k string, n uint8) (uint8, error) {
   414  	c.mu.Lock()
   415  	v, found := c.items[k]
   416  	if !found || v.Expired() {
   417  		c.mu.Unlock()
   418  		return 0, fmt.Errorf("Item %s not found", k)
   419  	}
   420  	rv, ok := v.Object.(uint8)
   421  	if !ok {
   422  		c.mu.Unlock()
   423  		return 0, fmt.Errorf("The value for %s is not an uint8", k)
   424  	}
   425  	nv := rv + n
   426  	v.Object = nv
   427  	c.items[k] = v
   428  	c.mu.Unlock()
   429  	return nv, nil
   430  }
   431  
   432  // Increment an item of type uint16 by n. Returns an error if the item's value
   433  // is not an uint16, or if it was not found. If there is no error, the
   434  // incremented value is returned.
   435  func (c *cache) IncrementUint16(k string, n uint16) (uint16, error) {
   436  	c.mu.Lock()
   437  	v, found := c.items[k]
   438  	if !found || v.Expired() {
   439  		c.mu.Unlock()
   440  		return 0, fmt.Errorf("Item %s not found", k)
   441  	}
   442  	rv, ok := v.Object.(uint16)
   443  	if !ok {
   444  		c.mu.Unlock()
   445  		return 0, fmt.Errorf("The value for %s is not an uint16", k)
   446  	}
   447  	nv := rv + n
   448  	v.Object = nv
   449  	c.items[k] = v
   450  	c.mu.Unlock()
   451  	return nv, nil
   452  }
   453  
   454  // Increment an item of type uint32 by n. Returns an error if the item's value
   455  // is not an uint32, or if it was not found. If there is no error, the
   456  // incremented value is returned.
   457  func (c *cache) IncrementUint32(k string, n uint32) (uint32, error) {
   458  	c.mu.Lock()
   459  	v, found := c.items[k]
   460  	if !found || v.Expired() {
   461  		c.mu.Unlock()
   462  		return 0, fmt.Errorf("Item %s not found", k)
   463  	}
   464  	rv, ok := v.Object.(uint32)
   465  	if !ok {
   466  		c.mu.Unlock()
   467  		return 0, fmt.Errorf("The value for %s is not an uint32", k)
   468  	}
   469  	nv := rv + n
   470  	v.Object = nv
   471  	c.items[k] = v
   472  	c.mu.Unlock()
   473  	return nv, nil
   474  }
   475  
   476  // Increment an item of type uint64 by n. Returns an error if the item's value
   477  // is not an uint64, or if it was not found. If there is no error, the
   478  // incremented value is returned.
   479  func (c *cache) IncrementUint64(k string, n uint64) (uint64, error) {
   480  	c.mu.Lock()
   481  	v, found := c.items[k]
   482  	if !found || v.Expired() {
   483  		c.mu.Unlock()
   484  		return 0, fmt.Errorf("Item %s not found", k)
   485  	}
   486  	rv, ok := v.Object.(uint64)
   487  	if !ok {
   488  		c.mu.Unlock()
   489  		return 0, fmt.Errorf("The value for %s is not an uint64", k)
   490  	}
   491  	nv := rv + n
   492  	v.Object = nv
   493  	c.items[k] = v
   494  	c.mu.Unlock()
   495  	return nv, nil
   496  }
   497  
   498  // Increment an item of type float32 by n. Returns an error if the item's value
   499  // is not an float32, or if it was not found. If there is no error, the
   500  // incremented value is returned.
   501  func (c *cache) IncrementFloat32(k string, n float32) (float32, error) {
   502  	c.mu.Lock()
   503  	v, found := c.items[k]
   504  	if !found || v.Expired() {
   505  		c.mu.Unlock()
   506  		return 0, fmt.Errorf("Item %s not found", k)
   507  	}
   508  	rv, ok := v.Object.(float32)
   509  	if !ok {
   510  		c.mu.Unlock()
   511  		return 0, fmt.Errorf("The value for %s is not an float32", k)
   512  	}
   513  	nv := rv + n
   514  	v.Object = nv
   515  	c.items[k] = v
   516  	c.mu.Unlock()
   517  	return nv, nil
   518  }
   519  
   520  // Increment an item of type float64 by n. Returns an error if the item's value
   521  // is not an float64, or if it was not found. If there is no error, the
   522  // incremented value is returned.
   523  func (c *cache) IncrementFloat64(k string, n float64) (float64, error) {
   524  	c.mu.Lock()
   525  	v, found := c.items[k]
   526  	if !found || v.Expired() {
   527  		c.mu.Unlock()
   528  		return 0, fmt.Errorf("Item %s not found", k)
   529  	}
   530  	rv, ok := v.Object.(float64)
   531  	if !ok {
   532  		c.mu.Unlock()
   533  		return 0, fmt.Errorf("The value for %s is not an float64", k)
   534  	}
   535  	nv := rv + n
   536  	v.Object = nv
   537  	c.items[k] = v
   538  	c.mu.Unlock()
   539  	return nv, nil
   540  }
   541  
   542  // Decrement an item of type int, int8, int16, int32, int64, uintptr, uint,
   543  // uint8, uint32, or uint64, float32 or float64 by n. Returns an error if the
   544  // item's value is not an integer, if it was not found, or if it is not
   545  // possible to decrement it by n. To retrieve the decremented value, use one
   546  // of the specialized methods, e.g. DecrementInt64.
   547  func (c *cache) Decrement(k string, n int64) error {
   548  	// TODO: Implement Increment and Decrement more cleanly.
   549  	// (Cannot do Increment(k, n*-1) for uints.)
   550  	c.mu.Lock()
   551  	v, found := c.items[k]
   552  	if !found || v.Expired() {
   553  		c.mu.Unlock()
   554  		return fmt.Errorf("Item not found")
   555  	}
   556  	switch v.Object.(type) {
   557  	case int:
   558  		v.Object = v.Object.(int) - int(n)
   559  	case int8:
   560  		v.Object = v.Object.(int8) - int8(n)
   561  	case int16:
   562  		v.Object = v.Object.(int16) - int16(n)
   563  	case int32:
   564  		v.Object = v.Object.(int32) - int32(n)
   565  	case int64:
   566  		v.Object = v.Object.(int64) - n
   567  	case uint:
   568  		v.Object = v.Object.(uint) - uint(n)
   569  	case uintptr:
   570  		v.Object = v.Object.(uintptr) - uintptr(n)
   571  	case uint8:
   572  		v.Object = v.Object.(uint8) - uint8(n)
   573  	case uint16:
   574  		v.Object = v.Object.(uint16) - uint16(n)
   575  	case uint32:
   576  		v.Object = v.Object.(uint32) - uint32(n)
   577  	case uint64:
   578  		v.Object = v.Object.(uint64) - uint64(n)
   579  	case float32:
   580  		v.Object = v.Object.(float32) - float32(n)
   581  	case float64:
   582  		v.Object = v.Object.(float64) - float64(n)
   583  	default:
   584  		c.mu.Unlock()
   585  		return fmt.Errorf("The value for %s is not an integer", k)
   586  	}
   587  	c.items[k] = v
   588  	c.mu.Unlock()
   589  	return nil
   590  }
   591  
   592  // Decrement an item of type float32 or float64 by n. Returns an error if the
   593  // item's value is not floating point, if it was not found, or if it is not
   594  // possible to decrement it by n. Pass a negative number to decrement the
   595  // value. To retrieve the decremented value, use one of the specialized methods,
   596  // e.g. DecrementFloat64.
   597  func (c *cache) DecrementFloat(k string, n float64) error {
   598  	c.mu.Lock()
   599  	v, found := c.items[k]
   600  	if !found || v.Expired() {
   601  		c.mu.Unlock()
   602  		return fmt.Errorf("Item %s not found", k)
   603  	}
   604  	switch v.Object.(type) {
   605  	case float32:
   606  		v.Object = v.Object.(float32) - float32(n)
   607  	case float64:
   608  		v.Object = v.Object.(float64) - n
   609  	default:
   610  		c.mu.Unlock()
   611  		return fmt.Errorf("The value for %s does not have type float32 or float64", k)
   612  	}
   613  	c.items[k] = v
   614  	c.mu.Unlock()
   615  	return nil
   616  }
   617  
   618  // Decrement an item of type int by n. Returns an error if the item's value is
   619  // not an int, or if it was not found. If there is no error, the decremented
   620  // value is returned.
   621  func (c *cache) DecrementInt(k string, n int) (int, error) {
   622  	c.mu.Lock()
   623  	v, found := c.items[k]
   624  	if !found || v.Expired() {
   625  		c.mu.Unlock()
   626  		return 0, fmt.Errorf("Item %s not found", k)
   627  	}
   628  	rv, ok := v.Object.(int)
   629  	if !ok {
   630  		c.mu.Unlock()
   631  		return 0, fmt.Errorf("The value for %s is not an int", k)
   632  	}
   633  	nv := rv - n
   634  	v.Object = nv
   635  	c.items[k] = v
   636  	c.mu.Unlock()
   637  	return nv, nil
   638  }
   639  
   640  // Decrement an item of type int8 by n. Returns an error if the item's value is
   641  // not an int8, or if it was not found. If there is no error, the decremented
   642  // value is returned.
   643  func (c *cache) DecrementInt8(k string, n int8) (int8, error) {
   644  	c.mu.Lock()
   645  	v, found := c.items[k]
   646  	if !found || v.Expired() {
   647  		c.mu.Unlock()
   648  		return 0, fmt.Errorf("Item %s not found", k)
   649  	}
   650  	rv, ok := v.Object.(int8)
   651  	if !ok {
   652  		c.mu.Unlock()
   653  		return 0, fmt.Errorf("The value for %s is not an int8", k)
   654  	}
   655  	nv := rv - n
   656  	v.Object = nv
   657  	c.items[k] = v
   658  	c.mu.Unlock()
   659  	return nv, nil
   660  }
   661  
   662  // Decrement an item of type int16 by n. Returns an error if the item's value is
   663  // not an int16, or if it was not found. If there is no error, the decremented
   664  // value is returned.
   665  func (c *cache) DecrementInt16(k string, n int16) (int16, error) {
   666  	c.mu.Lock()
   667  	v, found := c.items[k]
   668  	if !found || v.Expired() {
   669  		c.mu.Unlock()
   670  		return 0, fmt.Errorf("Item %s not found", k)
   671  	}
   672  	rv, ok := v.Object.(int16)
   673  	if !ok {
   674  		c.mu.Unlock()
   675  		return 0, fmt.Errorf("The value for %s is not an int16", k)
   676  	}
   677  	nv := rv - n
   678  	v.Object = nv
   679  	c.items[k] = v
   680  	c.mu.Unlock()
   681  	return nv, nil
   682  }
   683  
   684  // Decrement an item of type int32 by n. Returns an error if the item's value is
   685  // not an int32, or if it was not found. If there is no error, the decremented
   686  // value is returned.
   687  func (c *cache) DecrementInt32(k string, n int32) (int32, error) {
   688  	c.mu.Lock()
   689  	v, found := c.items[k]
   690  	if !found || v.Expired() {
   691  		c.mu.Unlock()
   692  		return 0, fmt.Errorf("Item %s not found", k)
   693  	}
   694  	rv, ok := v.Object.(int32)
   695  	if !ok {
   696  		c.mu.Unlock()
   697  		return 0, fmt.Errorf("The value for %s is not an int32", k)
   698  	}
   699  	nv := rv - n
   700  	v.Object = nv
   701  	c.items[k] = v
   702  	c.mu.Unlock()
   703  	return nv, nil
   704  }
   705  
   706  // Decrement an item of type int64 by n. Returns an error if the item's value is
   707  // not an int64, or if it was not found. If there is no error, the decremented
   708  // value is returned.
   709  func (c *cache) DecrementInt64(k string, n int64) (int64, error) {
   710  	c.mu.Lock()
   711  	v, found := c.items[k]
   712  	if !found || v.Expired() {
   713  		c.mu.Unlock()
   714  		return 0, fmt.Errorf("Item %s not found", k)
   715  	}
   716  	rv, ok := v.Object.(int64)
   717  	if !ok {
   718  		c.mu.Unlock()
   719  		return 0, fmt.Errorf("The value for %s is not an int64", k)
   720  	}
   721  	nv := rv - n
   722  	v.Object = nv
   723  	c.items[k] = v
   724  	c.mu.Unlock()
   725  	return nv, nil
   726  }
   727  
   728  // Decrement an item of type uint by n. Returns an error if the item's value is
   729  // not an uint, or if it was not found. If there is no error, the decremented
   730  // value is returned.
   731  func (c *cache) DecrementUint(k string, n uint) (uint, error) {
   732  	c.mu.Lock()
   733  	v, found := c.items[k]
   734  	if !found || v.Expired() {
   735  		c.mu.Unlock()
   736  		return 0, fmt.Errorf("Item %s not found", k)
   737  	}
   738  	rv, ok := v.Object.(uint)
   739  	if !ok {
   740  		c.mu.Unlock()
   741  		return 0, fmt.Errorf("The value for %s is not an uint", k)
   742  	}
   743  	nv := rv - n
   744  	v.Object = nv
   745  	c.items[k] = v
   746  	c.mu.Unlock()
   747  	return nv, nil
   748  }
   749  
   750  // Decrement an item of type uintptr by n. Returns an error if the item's value
   751  // is not an uintptr, or if it was not found. If there is no error, the
   752  // decremented value is returned.
   753  func (c *cache) DecrementUintptr(k string, n uintptr) (uintptr, error) {
   754  	c.mu.Lock()
   755  	v, found := c.items[k]
   756  	if !found || v.Expired() {
   757  		c.mu.Unlock()
   758  		return 0, fmt.Errorf("Item %s not found", k)
   759  	}
   760  	rv, ok := v.Object.(uintptr)
   761  	if !ok {
   762  		c.mu.Unlock()
   763  		return 0, fmt.Errorf("The value for %s is not an uintptr", k)
   764  	}
   765  	nv := rv - n
   766  	v.Object = nv
   767  	c.items[k] = v
   768  	c.mu.Unlock()
   769  	return nv, nil
   770  }
   771  
   772  // Decrement an item of type uint8 by n. Returns an error if the item's value is
   773  // not an uint8, or if it was not found. If there is no error, the decremented
   774  // value is returned.
   775  func (c *cache) DecrementUint8(k string, n uint8) (uint8, error) {
   776  	c.mu.Lock()
   777  	v, found := c.items[k]
   778  	if !found || v.Expired() {
   779  		c.mu.Unlock()
   780  		return 0, fmt.Errorf("Item %s not found", k)
   781  	}
   782  	rv, ok := v.Object.(uint8)
   783  	if !ok {
   784  		c.mu.Unlock()
   785  		return 0, fmt.Errorf("The value for %s is not an uint8", k)
   786  	}
   787  	nv := rv - n
   788  	v.Object = nv
   789  	c.items[k] = v
   790  	c.mu.Unlock()
   791  	return nv, nil
   792  }
   793  
   794  // Decrement an item of type uint16 by n. Returns an error if the item's value
   795  // is not an uint16, or if it was not found. If there is no error, the
   796  // decremented value is returned.
   797  func (c *cache) DecrementUint16(k string, n uint16) (uint16, error) {
   798  	c.mu.Lock()
   799  	v, found := c.items[k]
   800  	if !found || v.Expired() {
   801  		c.mu.Unlock()
   802  		return 0, fmt.Errorf("Item %s not found", k)
   803  	}
   804  	rv, ok := v.Object.(uint16)
   805  	if !ok {
   806  		c.mu.Unlock()
   807  		return 0, fmt.Errorf("The value for %s is not an uint16", k)
   808  	}
   809  	nv := rv - n
   810  	v.Object = nv
   811  	c.items[k] = v
   812  	c.mu.Unlock()
   813  	return nv, nil
   814  }
   815  
   816  // Decrement an item of type uint32 by n. Returns an error if the item's value
   817  // is not an uint32, or if it was not found. If there is no error, the
   818  // decremented value is returned.
   819  func (c *cache) DecrementUint32(k string, n uint32) (uint32, error) {
   820  	c.mu.Lock()
   821  	v, found := c.items[k]
   822  	if !found || v.Expired() {
   823  		c.mu.Unlock()
   824  		return 0, fmt.Errorf("Item %s not found", k)
   825  	}
   826  	rv, ok := v.Object.(uint32)
   827  	if !ok {
   828  		c.mu.Unlock()
   829  		return 0, fmt.Errorf("The value for %s is not an uint32", k)
   830  	}
   831  	nv := rv - n
   832  	v.Object = nv
   833  	c.items[k] = v
   834  	c.mu.Unlock()
   835  	return nv, nil
   836  }
   837  
   838  // Decrement an item of type uint64 by n. Returns an error if the item's value
   839  // is not an uint64, or if it was not found. If there is no error, the
   840  // decremented value is returned.
   841  func (c *cache) DecrementUint64(k string, n uint64) (uint64, error) {
   842  	c.mu.Lock()
   843  	v, found := c.items[k]
   844  	if !found || v.Expired() {
   845  		c.mu.Unlock()
   846  		return 0, fmt.Errorf("Item %s not found", k)
   847  	}
   848  	rv, ok := v.Object.(uint64)
   849  	if !ok {
   850  		c.mu.Unlock()
   851  		return 0, fmt.Errorf("The value for %s is not an uint64", k)
   852  	}
   853  	nv := rv - n
   854  	v.Object = nv
   855  	c.items[k] = v
   856  	c.mu.Unlock()
   857  	return nv, nil
   858  }
   859  
   860  // Decrement an item of type float32 by n. Returns an error if the item's value
   861  // is not an float32, or if it was not found. If there is no error, the
   862  // decremented value is returned.
   863  func (c *cache) DecrementFloat32(k string, n float32) (float32, error) {
   864  	c.mu.Lock()
   865  	v, found := c.items[k]
   866  	if !found || v.Expired() {
   867  		c.mu.Unlock()
   868  		return 0, fmt.Errorf("Item %s not found", k)
   869  	}
   870  	rv, ok := v.Object.(float32)
   871  	if !ok {
   872  		c.mu.Unlock()
   873  		return 0, fmt.Errorf("The value for %s is not an float32", k)
   874  	}
   875  	nv := rv - n
   876  	v.Object = nv
   877  	c.items[k] = v
   878  	c.mu.Unlock()
   879  	return nv, nil
   880  }
   881  
   882  // Decrement an item of type float64 by n. Returns an error if the item's value
   883  // is not an float64, or if it was not found. If there is no error, the
   884  // decremented value is returned.
   885  func (c *cache) DecrementFloat64(k string, n float64) (float64, error) {
   886  	c.mu.Lock()
   887  	v, found := c.items[k]
   888  	if !found || v.Expired() {
   889  		c.mu.Unlock()
   890  		return 0, fmt.Errorf("Item %s not found", k)
   891  	}
   892  	rv, ok := v.Object.(float64)
   893  	if !ok {
   894  		c.mu.Unlock()
   895  		return 0, fmt.Errorf("The value for %s is not an float64", k)
   896  	}
   897  	nv := rv - n
   898  	v.Object = nv
   899  	c.items[k] = v
   900  	c.mu.Unlock()
   901  	return nv, nil
   902  }
   903  
   904  // Delete an item from the cache. Does nothing if the key is not in the cache.
   905  func (c *cache) Delete(k string) {
   906  	c.mu.Lock()
   907  	v, evicted := c.delete(k)
   908  	c.mu.Unlock()
   909  	if evicted {
   910  		c.onEvicted(k, v)
   911  	}
   912  }
   913  
   914  func (c *cache) delete(k string) (interface{}, bool) {
   915  	if c.onEvicted != nil {
   916  		if v, found := c.items[k]; found {
   917  			delete(c.items, k)
   918  			return v.Object, true
   919  		}
   920  	}
   921  	delete(c.items, k)
   922  	return nil, false
   923  }
   924  
   925  type keyAndValue struct {
   926  	key   string
   927  	value interface{}
   928  }
   929  
   930  // Delete all expired items from the cache.
   931  func (c *cache) DeleteExpired() {
   932  	var evictedItems []keyAndValue
   933  	now := time.Now().UnixNano()
   934  	c.mu.Lock()
   935  	for k, v := range c.items {
   936  		// "Inlining" of expired
   937  		if v.Expiration > 0 && now > v.Expiration {
   938  			ov, evicted := c.delete(k)
   939  			if evicted {
   940  				evictedItems = append(evictedItems, keyAndValue{k, ov})
   941  			}
   942  		}
   943  	}
   944  	c.mu.Unlock()
   945  	for _, v := range evictedItems {
   946  		c.onEvicted(v.key, v.value)
   947  	}
   948  }
   949  
   950  // Sets an (optional) function that is called with the key and value when an
   951  // item is evicted from the cache. (Including when it is deleted manually, but
   952  // not when it is overwritten.) Set to nil to disable.
   953  func (c *cache) OnEvicted(f func(string, interface{})) {
   954  	c.mu.Lock()
   955  	c.onEvicted = f
   956  	c.mu.Unlock()
   957  }
   958  
   959  // Write the cache's items (using Gob) to an io.Writer.
   960  //
   961  // NOTE: This method is deprecated in favor of c.Items() and NewFrom() (see the
   962  // documentation for NewFrom().)
   963  func (c *cache) Save(w io.Writer) (err error) {
   964  	enc := gob.NewEncoder(w)
   965  	defer func() {
   966  		if x := recover(); x != nil {
   967  			err = fmt.Errorf("Error registering item types with Gob library")
   968  		}
   969  	}()
   970  	c.mu.RLock()
   971  	defer c.mu.RUnlock()
   972  	for _, v := range c.items {
   973  		gob.Register(v.Object)
   974  	}
   975  	err = enc.Encode(&c.items)
   976  	return
   977  }
   978  
   979  // Save the cache's items to the given filename, creating the file if it
   980  // doesn't exist, and overwriting it if it does.
   981  //
   982  // NOTE: This method is deprecated in favor of c.Items() and NewFrom() (see the
   983  // documentation for NewFrom().)
   984  func (c *cache) SaveFile(fname string) error {
   985  	fp, err := os.Create(fname)
   986  	if err != nil {
   987  		return err
   988  	}
   989  	err = c.Save(fp)
   990  	if err != nil {
   991  		fp.Close()
   992  		return err
   993  	}
   994  	return fp.Close()
   995  }
   996  
   997  // Add (Gob-serialized) cache items from an io.Reader, excluding any items with
   998  // keys that already exist (and haven't expired) in the current cache.
   999  //
  1000  // NOTE: This method is deprecated in favor of c.Items() and NewFrom() (see the
  1001  // documentation for NewFrom().)
  1002  func (c *cache) Load(r io.Reader) error {
  1003  	dec := gob.NewDecoder(r)
  1004  	items := map[string]Item{}
  1005  	err := dec.Decode(&items)
  1006  	if err == nil {
  1007  		c.mu.Lock()
  1008  		defer c.mu.Unlock()
  1009  		for k, v := range items {
  1010  			ov, found := c.items[k]
  1011  			if !found || ov.Expired() {
  1012  				c.items[k] = v
  1013  			}
  1014  		}
  1015  	}
  1016  	return err
  1017  }
  1018  
  1019  // Load and add cache items from the given filename, excluding any items with
  1020  // keys that already exist in the current cache.
  1021  //
  1022  // NOTE: This method is deprecated in favor of c.Items() and NewFrom() (see the
  1023  // documentation for NewFrom().)
  1024  func (c *cache) LoadFile(fname string) error {
  1025  	fp, err := os.Open(fname)
  1026  	if err != nil {
  1027  		return err
  1028  	}
  1029  	err = c.Load(fp)
  1030  	if err != nil {
  1031  		fp.Close()
  1032  		return err
  1033  	}
  1034  	return fp.Close()
  1035  }
  1036  
  1037  // Copies all unexpired items in the cache into a new map and returns it.
  1038  func (c *cache) Items() map[string]Item {
  1039  	c.mu.RLock()
  1040  	defer c.mu.RUnlock()
  1041  	m := make(map[string]Item, len(c.items))
  1042  	now := time.Now().UnixNano()
  1043  	for k, v := range c.items {
  1044  		// "Inlining" of Expired
  1045  		if v.Expiration > 0 {
  1046  			if now > v.Expiration {
  1047  				continue
  1048  			}
  1049  		}
  1050  		m[k] = v
  1051  	}
  1052  	return m
  1053  }
  1054  
  1055  // Returns the number of items in the cache. This may include items that have
  1056  // expired, but have not yet been cleaned up.
  1057  func (c *cache) ItemCount() int {
  1058  	c.mu.RLock()
  1059  	n := len(c.items)
  1060  	c.mu.RUnlock()
  1061  	return n
  1062  }
  1063  
  1064  // Delete all items from the cache.
  1065  func (c *cache) Flush() {
  1066  	c.mu.Lock()
  1067  	c.items = map[string]Item{}
  1068  	c.mu.Unlock()
  1069  }
  1070  
  1071  type janitor struct {
  1072  	Interval time.Duration
  1073  	stop     chan bool
  1074  }
  1075  
  1076  func (j *janitor) Run(c *cache) {
  1077  	ticker := time.NewTicker(j.Interval)
  1078  	for {
  1079  		select {
  1080  		case <-ticker.C:
  1081  			c.DeleteExpired()
  1082  		case <-j.stop:
  1083  			ticker.Stop()
  1084  			return
  1085  		}
  1086  	}
  1087  }
  1088  
  1089  func stopJanitor(c *Cache) {
  1090  	c.janitor.stop <- true
  1091  }
  1092  
  1093  func runJanitor(c *cache, ci time.Duration) {
  1094  	j := &janitor{
  1095  		Interval: ci,
  1096  		stop:     make(chan bool),
  1097  	}
  1098  	c.janitor = j
  1099  	go j.Run(c)
  1100  }
  1101  
  1102  func newCache(de time.Duration, m map[string]Item) *cache {
  1103  	if de == 0 {
  1104  		de = -1
  1105  	}
  1106  	c := &cache{
  1107  		defaultExpiration: de,
  1108  		items:             m,
  1109  	}
  1110  	return c
  1111  }
  1112  
  1113  func newCacheWithJanitor(de time.Duration, ci time.Duration, m map[string]Item) *Cache {
  1114  	c := newCache(de, m)
  1115  	// This trick ensures that the janitor goroutine (which--granted it
  1116  	// was enabled--is running DeleteExpired on c forever) does not keep
  1117  	// the returned C object from being garbage collected. When it is
  1118  	// garbage collected, the finalizer stops the janitor goroutine, after
  1119  	// which c can be collected.
  1120  	C := &Cache{c}
  1121  	if ci > 0 {
  1122  		runJanitor(c, ci)
  1123  		runtime.SetFinalizer(C, stopJanitor)
  1124  	}
  1125  	return C
  1126  }
  1127  
  1128  // Return a new cache with a given default expiration duration and cleanup
  1129  // interval. If the expiration duration is less than one (or NoExpiration),
  1130  // the items in the cache never expire (by default), and must be deleted
  1131  // manually. If the cleanup interval is less than one, expired items are not
  1132  // deleted from the cache before calling c.DeleteExpired().
  1133  func New(defaultExpiration, cleanupInterval time.Duration) *Cache {
  1134  	items := make(map[string]Item)
  1135  	return newCacheWithJanitor(defaultExpiration, cleanupInterval, items)
  1136  }
  1137  
  1138  // Return a new cache with a given default expiration duration and cleanup
  1139  // interval. If the expiration duration is less than one (or NoExpiration),
  1140  // the items in the cache never expire (by default), and must be deleted
  1141  // manually. If the cleanup interval is less than one, expired items are not
  1142  // deleted from the cache before calling c.DeleteExpired().
  1143  //
  1144  // NewFrom() also accepts an items map which will serve as the underlying map
  1145  // for the cache. This is useful for starting from a deserialized cache
  1146  // (serialized using e.g. gob.Encode() on c.Items()), or passing in e.g.
  1147  // make(map[string]Item, 500) to improve startup performance when the cache
  1148  // is expected to reach a certain minimum size.
  1149  //
  1150  // Only the cache's methods synchronize access to this map, so it is not
  1151  // recommended to keep any references to the map around after creating a cache.
  1152  // If need be, the map can be accessed at a later point using c.Items() (subject
  1153  // to the same caveat.)
  1154  //
  1155  // Note regarding serialization: When using e.g. gob, make sure to
  1156  // gob.Register() the individual types stored in the cache before encoding a
  1157  // map retrieved with c.Items(), and to register those same types before
  1158  // decoding a blob containing an items map.
  1159  func NewFrom(defaultExpiration, cleanupInterval time.Duration, items map[string]Item) *Cache {
  1160  	return newCacheWithJanitor(defaultExpiration, cleanupInterval, items)
  1161  }
  1162
View as plain text