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
• func WithExpiration(expiration time.Time) *time.Time
• func WithTTL(duration time.Duration) *time.Time
• type Item
  • func NewItem(value interface{}, expiration *time.Time) Item
  • func (item *Item) Expiration() time.Time
  • func (item *Item) Expired() bool
  • func (item *Item) Expires() bool
  • func (item *Item) TTL() time.Duration
  • func (item *Item) Value() interface{}
• type KeyExistMode
• type Map
  • func New(opts *Options) *Map
  • func (m *Map) Delete(key string) (Item, error)
  • func (m *Map) Drain()
  • func (m *Map) Draining() <-chan struct{}
  • func (m *Map) Get(key string) (Item, error)
  • func (m *Map) Len() int
  • func (m *Map) Range(num int) []*Item
  • func (m *Map) Set(key string, item Item, opts *SetOptions) error
  • func (m *Map) Update(key string, item Item, opts *UpdateOptions) (Item, error)
• type Options
• type SetOptions
• type UpdateOptions

Variables

var (
	ErrNotExist = errors.New("key does not exist")
	ErrExist    = errors.New("key already exists")
	ErrDrained  = errors.New("map was drained")
)

Errors returned Map operations.

Functions

func WithExpiration

func WithExpiration(expiration time.Time) *time.Time

WithExpiration creates an expiration time.

func WithTTL

func WithTTL(duration time.Duration) *time.Time

WithTTL creates an expiration time from a specified TTL.

Types

type Item

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

Item represents an item with an associated value and optional expiration.

func NewItem

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

NewItem creates an item with the specified value and optional expiration.

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) Expires

func (item *Item) Expires() bool

Expires checks whether the item has an expiration time set.

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 KeyExistMode

type KeyExistMode int

KeyExistMode represents a restriction on the existence of a key for the operation to succeed.

const (
	// KeyExistDontCare can be used to ignore wether a key exists or not.
	KeyExistDontCare KeyExistMode = 0
	// KeyExistNotYet fails the operation if the key exists already.
	KeyExistNotYet KeyExistMode = 1
	// KeyExistAlready fails the opration if the key does not exist already.
	KeyExistAlready KeyExistMode = 2
)

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, error)

Delete deletes the item with the specified key from the map. ErrNotExist will be returned if the key does not exist. ErrDrained will be returned if the map is already drained.

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, error)

Get returns the item in the map with the given key. ErrNotExist will be returned if the key does not exist. ErrDrained will be returned if the map is already drained.

func (*Map) Len

func (m *Map) Len() int

Len returns the number of elements in the map.

func (*Map) Range

func (m *Map) Range(num int) []*Item

Range of Map

func (*Map) Set

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

Set assigns an item with the specified key in the map. ErrExist or ErrNotExist may be returned depending on opts.KeyExist. ErrDrained will be returned if the map is already drained.

func (*Map) Update

func (m *Map) Update(key string, item Item, opts *UpdateOptions) (Item, error)

Update updates an item with the specified key in the map and returns it. ErrNotExist will be returned if the key does not exist. 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 new Map.

type SetOptions

type SetOptions struct {
	KeyExist KeyExistMode
}

SetOptions for setting items on a Map.

type UpdateOptions

type UpdateOptions struct {
	KeepValue      bool
	KeepExpiration bool
}

UpdateOptions for updating items on a Map.