ttlmap

README

go-ttlmap

go-ttlmap is a Go package that provides an in-memory key-value cache with notification events for storing TTL-based expirable items.

Install

First, you need to install the package:

go get -u github.com/imkira/go-ttlmap

Documentation

For advanced usage, make sure to check the available documentation here.

Examples

For examples check out the following code.

Contribute

Found a bug? Want to contribute and add a new feature?

Please fork this project and send me a pull request!

License

go-ttlmap is licensed under the MIT license:

www.opensource.org/licenses/MIT

Copyright

Copyright (c) 2016 Mario Freitas. See LICENSE for further details.

Documentation

Overview

Package ttlmap provides a map-like interface with string keys and expirable items. Keys are currently limited to strings.

Index

• Variables
• type Item
  • func NewItem(value interface{}, expiration time.Time) *Item
  • func NewItemWithTTL(value interface{}, duration time.Duration) *Item
  • func (item *Item) Expiration() time.Time
  • func (item *Item) Expired() bool
  • func (item *Item) TTL() time.Duration
  • func (item *Item) Value() interface{}
• type Map
  • func New(opts *Options) *Map
  • func (m *Map) Delete(key string) *Item
  • func (m *Map) Drain()
  • func (m *Map) Draining() <-chan struct{}
  • func (m *Map) Get(key string) *Item
  • func (m *Map) Len() int
  • func (m *Map) Set(key string, item *Item) error
  • func (m *Map) SetNX(key string, item *Item) error
• type Options

Variables

var (
	ErrExists  = errors.New("item already exists")
	ErrDrained = errors.New("map was drained")
)

Errors returned by Set and SetNX operations.

Types

type Item

type Item struct {
	// contains filtered or unexported fields
}

Item represents an expirable item associated with a given value.

func NewItem

func NewItem(value interface{}, expiration time.Time) *Item

NewItem creates an item with the specified value and expiring on the specified time.

func NewItemWithTTL

func NewItemWithTTL(value interface{}, duration time.Duration) *Item

NewItemWithTTL creates an item with the specified value and expiring after the specified duration.

func (*Item) Expiration

func (item *Item) Expiration() time.Time

Expiration returns the item's expiration time.

func (*Item) Expired

func (item *Item) Expired() bool

Expired checks whether the item is already expired.

func (*Item) TTL

func (item *Item) TTL() time.Duration

TTL returns the remaining duration until expiration (negative if expired).

func (*Item) Value

func (item *Item) Value() interface{}

Value returns the value stored in the item.

type Map

type Map struct {
	// contains filtered or unexported fields
}

Map is the equivalent of a map[string]interface{} but with expirable Items.

func New

func New(opts *Options) *Map

New creates a new Map with given options.

func (*Map) Delete

func (m *Map) Delete(key string) *Item

Delete deletes the item with the specified key in the map. If an item is found, it is returned.

func (*Map) Drain

func (m *Map) Drain()

Drain evicts all remaining elements from the map and terminates the usage of this map.

func (*Map) Draining

func (m *Map) Draining() <-chan struct{}

Draining returns the channel that is closed when the map starts draining.

func (*Map) Get

func (m *Map) Get(key string) *Item

Get returns the item in the map given its key.

func (*Map) Len

func (m *Map) Len() int

Len returns the number of elements in the map.

func (*Map) Set

func (m *Map) Set(key string, item *Item) error

Set assigns an expirable Item with the specified key in the map. ErrDrained will be returned if the map is already drained.

func (*Map) SetNX

func (m *Map) SetNX(key string, item *Item) error

SetNX assigns an expirable Item with the specified key in the map, only if the key is not already being in use. ErrExists will be returned if the key already exists. ErrDrained will be returned if the map is already drained.

type Options

type Options struct {
	InitialCapacity int
	OnWillExpire    func(key string, item *Item)
	OnWillEvict     func(key string, item *Item)
}

Options for initializing a Map.