cache

package module
v0.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 11, 2022 License: BSD-3-Clause Imports: 18 Imported by: 14

README

go-cache

There are many interfaces for caching things. This one is ours. It reads and writes io.ReadSeekCloser instances.

This package supersedes go-whosonfirst-cache which will be retired soon.

Example

Caches are instantiated with the cache.NewCache method which takes as its arguments a context.Context instance and a URI string. The URI's scheme represents the type of cache it implements and the remaining (URI) properties are used by that cache type to instantiate itself.

For example to cache files to/from a directory on the local filesystem you would write:

import (
	"context"
	"flag"
	"github.com/whosonfirst/go-cache"
	"log"
)

func main() {

	ctx := context.Background()
	c, _ := cache.NewCache(ctx, "fs:///usr/local/cache")

	str, err := cache.GetString(c, "some-key")

	if err != nil && !cache.IsCacheMiss(err) {
		log.Fatal(err)
	}

	str, _ := cache.SetString(ctx, c, "some-key", "some-value")

	str2, _ := cache.GetString(ctx, c, "some-key")

	log.Println(str2)
}

Two things to note:

  • The use of the fs:// scheme rather than the more conventional file://. This is deliberate so as not to overlap with the Go Cloud Blob package's file handler.

  • The use of the cache.GetString and cache.SetString methods. The cache.Cache interface expects io.ReadSeekCloser instances so these methods are shortcuts to hide the boilerplate code necessary to work with io.ReadSeekCloser interfaces.

There is also a handy null:// cache which doesn't do anything at all (expect implement the cache.Cache interface). For example:

	ctx := context.Background()
	c, _ := cache.NewCache(ctx, "null://")

Interfaces

cache.Cache
type Cache interface {
     	Name() string
	Close(context.Context) error
	Get(context.Context, string) (io.ReadSeekCloser, error)
	Set(context.Context, string, io.ReadSeekCloser) (io.ReadSeekCloser, error)
	Unset(context.Context, string) error
	Hits() int64
	Misses() int64
	Evictions() int64
	Size() int64
	SizeWithContext(context.Context) int64
}

Custom caches

Custom caches need to:

  1. Implement the interface above.
  2. Announce their availability using the go-cache.Cache method on initialization.

For example, here is an abbreviated example of how the go-cache-blob is implemented:

package cache

import (
	"bufio"
	"bytes"
	"context"
	wof_cache "github.com/whosonfirst/go-cache"
	"gocloud.dev/blob"
	"io"
	"io/ioutil"
	"sync/atomic"
)

type BlobCache struct {
	wof_cache.Cache
	TTL       int64
	bucket    *blob.Bucket
	hits      int64
	misses    int64
	sets      int64
	evictions int64
}

func init() {
	ctx := context.Background()

	for _, scheme := range blob.DefaultURLMux().BucketSchemes() {
		wof_cache.RegisterCache(ctx, scheme, NewBlobCache)
	}
}

Note: See the way we're registering available cache types based on the the list of available Go Cloud Bucket schemes? By design the go-cache-blob doesn't try to load any Go Cloud providers. That is left up to your code.

func NewBlobCache() wof_cache.Cache {

	bucket, err := blob.OpenBucket(ctx, uri)

	if err != nil {
		return nil, err
	}

	c := &BlobCache{
		TTL:       0,
		misses:    0,
		sets:      0,
		evictions: 0,
		bucket:    bucket,
	}

	return c
}

And then to use it you would do this:

package main

import (
	"context"
	"github.com/whosonfirst/go-cache"
	_ "github.com/whosonfirst/go-cache-blob"
	_ "gocloud.dev/blob/memblob"
)

func main() {
	ctx := context.Background()
	c, _ := cache.NewCache(ctx, "mem://")
	fh, _ := c.Get(ctx, "some-key")
}

Available caches

"blob"

Cache data using any registered Go Cloud Blob source. For example:

import (
	"context"
	"github.com/whosonfirst/go-cache"
	_ "github.com/whosonfirst/go-cache-blob"
	_ "gocloud.dev/blob/s3blob"	
)

func main() {
	ctx := context.Background()
	c, _ := cache.NewCache(ctx, "s3://cache-bucket?region=us-west-1")
}
fs://

Cache data using a local filesystem.

import (
	"context"
	"github.com/whosonfirst/go-cache"
)

func main() {
	ctx := context.Background()
	c, _ := cache.NewCache(ctx, "fs:///usr/local/cache")
}
gocache://

Cache data using a go-cache backend.

import (
	"context"
	"github.com/whosonfirst/go-cache"
)

func main() {
	ctx := context.Background()
	c, _ := cache.NewCache(ctx, "gocache://")
}

To specify custom values for the DefaultExpiration and CleanupInterval properties pass use the default_expiration and cleanup_interval parameters, respectively. For example:

	c, _ := cache.NewCache(ctx, "gocache://?default_expiration=300&cleanup_interval=200")
null://

Pretend to cache data.

import (
	"context"
	"github.com/whosonfirst/go-cache"
)

func main() {
	ctx := context.Background()
	c, _ := cache.NewCache(ctx, "null://")
}

Documentation

Overview

package cache provides a storage-independent interface, and common implementations, for caching things. There are many interfaces for caching things. This one is ours. It reads and writes `io.ReadSeekCloser` instances.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetString 

func GetString(ctx context.Context, c Cache, k string) (string, error)

func IsCacheMiss 

func IsCacheMiss(e error) bool

func IsCacheMissMulti 

func IsCacheMissMulti(e error) bool

func ReadSeekCloserFromString added in v0.5.0 

func ReadSeekCloserFromString(v string) (io.ReadSeekCloser, error)

func RegisterCache added in v0.0.2 

func RegisterCache(ctx context.Context, name string, c CacheInitializationFunc) error

func SetString 

func SetString(ctx context.Context, c Cache, k string, v string) (string, error)

Types

type Cache 

type Cache interface {
	Close(context.Context) error
	Name() string
	Get(context.Context, string) (io.ReadSeekCloser, error)
	Set(context.Context, string, io.ReadSeekCloser) (io.ReadSeekCloser, error)
	Unset(context.Context, string) error
	Hits() int64
	Misses() int64
	Evictions() int64
	Size() int64
	SizeWithContext(context.Context) int64
}

func NewCache added in v0.0.2 

func NewCache(ctx context.Context, uri string) (Cache, error)

func NewFSCache 

func NewFSCache(ctx context.Context, uri string) (Cache, error)

func NewGoCache 

func NewGoCache(ctx context.Context, uri string) (Cache, error)

func NewMultiCache 

func NewMultiCache(ctx context.Context, str_uri string) (Cache, error)

func NewMultiCacheWithCaches added in v0.4.0 

func NewMultiCacheWithCaches(ctx context.Context, caches ...Cache) (Cache, error)

func NewNullCache 

func NewNullCache(ctx context.Context, uri string) (Cache, error)

type CacheInitializationFunc added in v0.1.0 

type CacheInitializationFunc func(ctx context.Context, uri string) (Cache, error)

type CacheMiss 

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

func (CacheMiss) Error 

func (m CacheMiss) Error() string

type CacheMissMulti 

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

func (CacheMissMulti) Error 

func (m CacheMissMulti) Error() string

type FSCache 

type FSCache struct {
	Cache

	TTL            int64
	FilePerms      os.FileMode
	DirectoryPerms os.FileMode
	// contains filtered or unexported fields
}

func (*FSCache) Close added in v0.0.2 

func (c *FSCache) Close(ctx context.Context) error

func (*FSCache) Evictions 

func (c *FSCache) Evictions() int64

func (*FSCache) Get 

func (c *FSCache) Get(ctx context.Context, key string) (io.ReadSeekCloser, error)

func (*FSCache) Hits 

func (c *FSCache) Hits() int64

func (*FSCache) Misses 

func (c *FSCache) Misses() int64

func (*FSCache) Name 

func (c *FSCache) Name() string

func (*FSCache) Set 

func (c *FSCache) Set(ctx context.Context, key string, fh io.ReadSeekCloser) (io.ReadSeekCloser, error)

func (*FSCache) Size 

func (c *FSCache) Size() int64

func (*FSCache) SizeWithContext 

func (c *FSCache) SizeWithContext(ctx context.Context) int64

func (*FSCache) Unset 

func (c *FSCache) Unset(ctx context.Context, key string) error

type GoCache 

type GoCache struct {
	Cache
	// contains filtered or unexported fields
}

func (*GoCache) Close added in v0.0.2 

func (c *GoCache) Close(ctx context.Context) error

func (*GoCache) Evictions 

func (c *GoCache) Evictions() int64

func (*GoCache) Get 

func (c *GoCache) Get(ctx context.Context, key string) (io.ReadSeekCloser, error)

func (*GoCache) Hits 

func (c *GoCache) Hits() int64

func (*GoCache) Misses 

func (c *GoCache) Misses() int64

func (*GoCache) Name 

func (c *GoCache) Name() string

func (*GoCache) Set 

func (c *GoCache) Set(ctx context.Context, key string, fh io.ReadSeekCloser) (io.ReadSeekCloser, error)

func (*GoCache) Size 

func (c *GoCache) Size() int64

func (*GoCache) SizeWithContext 

func (c *GoCache) SizeWithContext(ctx context.Context) int64

func (*GoCache) Unset 

func (c *GoCache) Unset(ctx context.Context, key string) error

type GoCacheOptions 

type GoCacheOptions struct {
	DefaultExpiration time.Duration
	CleanupInterval   time.Duration
}

func DefaultGoCacheOptions 

func DefaultGoCacheOptions() (*GoCacheOptions, error)

type MultiCache 

type MultiCache struct {
	Cache
	// contains filtered or unexported fields
}

func (*MultiCache) Close added in v0.2.0 

func (mc *MultiCache) Close(ctx context.Context) error

func (*MultiCache) Evictions 

func (mc *MultiCache) Evictions() int64

func (*MultiCache) Get 

func (mc *MultiCache) Get(ctx context.Context, key string) (io.ReadSeekCloser, error)

func (*MultiCache) Hits 

func (mc *MultiCache) Hits() int64

func (*MultiCache) Misses 

func (mc *MultiCache) Misses() int64

func (*MultiCache) Name 

func (mc *MultiCache) Name() string

func (*MultiCache) Set 

func (mc *MultiCache) Set(ctx context.Context, key string, fh io.ReadSeekCloser) (io.ReadSeekCloser, error)

func (*MultiCache) Size 

func (mc *MultiCache) Size() int64

func (*MultiCache) SizeWithContext 

func (mc *MultiCache) SizeWithContext(ctx context.Context) int64

func (*MultiCache) Unset 

func (mc *MultiCache) Unset(ctx context.Context, key string) error

type NullCache 

type NullCache struct {
	Cache
	// contains filtered or unexported fields
}

func (*NullCache) Close added in v0.0.2 

func (c *NullCache) Close(ctx context.Context) error

func (*NullCache) Evictions 

func (c *NullCache) Evictions() int64

func (*NullCache) Get 

func (c *NullCache) Get(ctx context.Context, key string) (io.ReadSeekCloser, error)

func (*NullCache) Hits 

func (c *NullCache) Hits() int64

func (*NullCache) Misses 

func (c *NullCache) Misses() int64

func (*NullCache) Name 

func (c *NullCache) Name() string

func (*NullCache) Set 

func (c *NullCache) Set(ctx context.Context, key string, fh io.ReadSeekCloser) (io.ReadSeekCloser, error)

func (*NullCache) Size 

func (c *NullCache) Size() int64

func (*NullCache) SizeWithContext 

func (c *NullCache) SizeWithContext(ctx context.Context) int64

func (*NullCache) Unset 

func (c *NullCache) Unset(ctx context.Context, key string) error

Source Files

View all Source files

Directories

Path Synopsis
cmd
wof-cache

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.