Build Status codecov Go Report Card GoDoc License



ttlcache – is a simple and efficient in-memory key value storage with TTL for each record.

The key is of uint64 type. Library provides wrappers for common types:

  • IntKey
  • ByteKey
  • Int8Key
  • Uint8Key
  • Int16Key
  • Uint16Key
  • Int32Key
  • Uint32Key
  • Int64Key
  • Uint64Key
  • BytesKey ([]byte)
  • StringKey
  • AnyKey (interface{})

AnyKey is not suitable for very intensive usage. Consider writing your own hash function if your keys are complex types, and you faced performance degradation.


go get -u


package main

import (

const (
    minute = 60 * time.Second
    hour = 60 * minute

func main() {
    // How often we need to stop the world and remove outdated records.
	resolution := minute

	cache := ttlcache.New(resolution)
	cache.Set(ttlcache.StringKey("some key"), "value", hour)
	value, ok := cache.Get(ttlcache.StringKey("some key"))
	if !ok {
		// there is no record with key "some key" in the cache. Probably it has been expired.

	fmt.Println(value.(string)) // This is necessary type assertion, because returned value is of interface{} type.


If you're interested in benchmarks you can check them in repository. Just play with numbers and types and check that library is suitable for your purposes.

go test -bench=. -benchmem

For those of us who wants to get some numbers without downloading unknown stuff (MacBook Pro 16"):

BenchmarkCache_Set-16            8755802               122 ns/op               8 B/op          0 allocs/op
BenchmarkCache_Get-16           57474564               19.6 ns/op              0 B/op          0 allocs/op
Expand ▾ Collapse ▴




This section is empty.


This section is empty.


func AnyKey

func AnyKey(k interface{}) uint64

    AnyKey creates key from anything. Should not be used for large datasets. For complex keys you can write your own hashing implementation.

    func ByteKey

    func ByteKey(k byte) uint64

      ByteKey creates key from byte value.

      func BytesKey

      func BytesKey(k []byte) uint64

        BytesKey creates key from slice of bytes value.

        func Int16Key

        func Int16Key(k int16) uint64

          Int16Key creates key from int16 value.

          func Int32Key

          func Int32Key(k int32) uint64

            Int32Key creates key from int32 value.

            func Int64Key

            func Int64Key(k int64) uint64

              Int64Key creates key from int64 value.

              func Int8Key

              func Int8Key(k int8) uint64

                Int8Key creates key from int8 value.

                func IntKey

                func IntKey(k int) uint64

                  IntKey creates key from int value.

                  func StringKey

                  func StringKey(k string) uint64

                    StringKey creates key from string value.

                    func Uint16Key

                    func Uint16Key(k uint16) uint64

                      Uint16Key creates key from uint16 value.

                      func Uint32Key

                      func Uint32Key(k uint32) uint64

                        Uint32Key creates key from uint32 value.

                        func Uint64Key

                        func Uint64Key(k uint64) uint64

                          Uint64Key creates key from uint64 value.

                          func Uint8Key

                          func Uint8Key(k uint8) uint64

                            Uint8Key creates key from uint8 value.


                            type Cache

                            type Cache struct {
                            	// contains filtered or unexported fields

                              Cache represents key-value storage.

                              func New

                              func New(resolution time.Duration) *Cache

                                New creates key-value storage. resolution – configures cleanup manager. Cleanup operation locks storage so think twice before setting it to small value.

                                func (*Cache) Close

                                func (c *Cache) Close() error

                                  Close stops cleanup manager and removes records from storage.

                                  func (*Cache) Delete

                                  func (c *Cache) Delete(key uint64)

                                    Delete removes record from storage.

                                    func (*Cache) Get

                                    func (c *Cache) Get(key uint64) (interface{}, bool)

                                      Get returns stored record. The first returned variable is a stored value. The second one is an existence flag like in the map.

                                      func (*Cache) Set

                                      func (c *Cache) Set(key uint64, value interface{}, ttl time.Duration)

                                        Set adds value to the cache with given ttl. ttl value should be a multiple of the resolution time value.

                                        Source Files