cmap

README

cmap

A thread-safe capacity-constrained hash table that evicts key/value pairs according to the LRU (least recently used) policy. It is technically a thin wrapper around Go's built-in map type.

Usage

package main

import (
    cmap "github.com/kchristidis/cmap
)

func main() {
    cm, err := cmap.New(2) // will hold up to 2 key/value pairs
    if err != nil {
        log.Fatal(err)
    }

    cm.Put("fooKey", "fooVal")
    v, ok := cm.Get("fooKey") // retrieve the value
    fmt.Println(ok)
    fmt.Println(v)

    cm.Put("barKey", "barVal") // retrieve value as above
    cm.Put("bazKey", "bazVal") // at this point "fooKey" is evicted

    _, ok = cm.Get("fooKey")
    fmt.Println(ok) // expected output: false
}

You may also want to consult the package documentation in GoDoc.

Contributing

Contributions are welcome. Fork this library and submit a pull request.

Documentation

Overview

Package cmap introduces a thead-safe capacity-constrained hash table that evicts key/value pairs according to the LRU (least recently used) policy.

It is technically a thin wrapper around Go's built-in map type.

Example

This example creates a cmap, fills it to capacity, then adds one more key/value pair to demonstrate that the LRU key has been evicted.

package main

import (
	"fmt"
	"log"

	"github.com/kchristidis/cmap"
)

func main() {
	cm, err := cmap.New(2) // will hold up to 2 key/value pairs
	if err != nil {
		log.Fatal(err)
	}

	cm.Put("fooKey", "fooVal")
	v, ok := cm.Get("fooKey") // retrieve the value
	fmt.Println(ok)
	fmt.Println(v)

	cm.Put("barKey", "barVal") // retrieve value as above
	cm.Put("bazKey", "bazVal") // at this point "fooKey" is evicted

	_, ok = cm.Get("fooKey")
	fmt.Println(ok) // expected output: false
}

Index

• Variables
• type Container
  • func New(cap int) (*Container, error)
  • func (cm *Container) Delete(key interface{}) bool
  • func (cm *Container) Get(key interface{}) (interface{}, bool)
  • func (cm *Container) Put(key, val interface{})

Examples

• Package

Variables

var ErrInvalidCapacity = errors.New("Capacity should be a positive integer")

ErrInvalidCapacity is the error returned when initializing a Map with an invalid capacity parameter.

Types

type Container

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

Container is a wrapper around Go's built-in map type that will only carry up to cap key-value pairs. An attempt to add a key/value pair to a cmap container that is already at capacity will succeed but will evict an existing key-value pair from the Container according to the LRU (least-recently used) policy.

func New

func New(cap int) (*Container, error)

New returns a cmap container that can carry up to cap key/value pairs. The parameter cap should be a positive integer.

func (*Container) Delete

func (cm *Container) Delete(key interface{}) bool

Delete removes the given key from the cmap container, if it exists.

func (*Container) Get

func (cm *Container) Get(key interface{}) (interface{}, bool)

Get returns the value that corresponds to the given key, if it exists.

func (*Container) Put

func (cm *Container) Put(key, val interface{})

Put adds the given key/value pair to the cmap container.