README
¶
go-filecache
This package provides file-based cache implementation with entries expiration, checksum validation and another useful features.
Methods that interacts with file system uses mutexes, so, this cache implementation thread-safe, but performance in this case can be less than you might want.
Installation and usage
The import path for the package is github.com/tarampampam/go-filecache.
To install it, run:
go get github.com/tarampampam/go-filecache
API documentation can be found here.
Usage example
package main
import (
"bytes"
"fmt"
"time"
filecache "github.com/tarampampam/go-filecache"
)
func main() {
// Create new cache items pool
// Note: Do NOT create new pool instance in goroutine - SHARE it instead
pool := filecache.NewPool("/tmp")
// Put data into cache pool with expiration time
expiresAt := time.Now().Add(time.Minute * 10)
if _, err := pool.Put("foo", bytes.NewBuffer([]byte("foo data")), expiresAt); err != nil {
panic(err)
}
// Put data without expiration time
if _, err := pool.PutForever("bar", bytes.NewBuffer([]byte("bar data"))); err != nil {
panic(err)
}
// Define buffer for cached data reading
buf := bytes.NewBuffer([]byte{})
// Read data using reader
if err := pool.GetItem("foo").Get(buf); err != nil {
panic(err)
}
fmt.Println(buf) // "foo data"
}
Simple benchmark (put value, get value, read into buffer and set new value) results:
goos: linux
goarch: amd64
pkg: github.com/tarampampam/go-filecache
BenchmarkSetAndGet-8 10000 611470 ns/op 40836 B/op 84 allocs/op
Testing
For application testing we use built-in golang testing feature and docker-ce + docker-compose as develop environment. So, just write into your terminal after repository cloning:
$ make test
Or execute benchmarks:
$ make gobench
Changelog
Changes log can be found here.
Support
If you will find any package errors, please, make an issue in current repository.
License
This is open-sourced software licensed under the MIT License.
Documentation
¶
Index ¶
- Variables
- type CacheItem
- type CachePool
- type Error
- type ErrorType
- type Item
- func (item *Item) ExpiresAt() *time.Time
- func (item *Item) Get(to io.Writer) error
- func (item *Item) GetFilePath() string
- func (item *Item) GetKey() string
- func (item *Item) IsExpired() (bool, error)
- func (item *Item) IsHit() bool
- func (item *Item) Set(from io.Reader) error
- func (item *Item) SetExpiresAt(when time.Time) error
- type Pool
- func (pool *Pool) Clear() (bool, error)
- func (pool *Pool) DeleteItem(key string) (bool, error)
- func (pool *Pool) GetDirPath() string
- func (pool *Pool) GetItem(key string) CacheItem
- func (pool *Pool) HasItem(key string) bool
- func (pool *Pool) Put(key string, from io.Reader, expiresAt time.Time) (CacheItem, error)
- func (pool *Pool) PutForever(key string, from io.Reader) (CacheItem, error)
Constants ¶
This section is empty.
Variables ¶
var DefaultItemFilePerms os.FileMode = 0664
DefaultItemFilePerms is default permissions for file, associated with cache item
var DefaultItemFileSignature file.FSignature = nil
DefaultItemFileSignature is default signature for cache files
Functions ¶
This section is empty.
Types ¶
type CacheItem ¶
type CacheItem interface {
// Returns path to the associated file.
GetFilePath() string
// Returns the key for the current cache item.
GetKey() string
// Retrieves the value of the item from the cache associated with this object's key.
Get(to io.Writer) error
// Confirms if the cache item lookup resulted in a cache hit.
IsHit() bool
// Sets the value represented by this cache item.
Set(from io.Reader) error
// Returns the expiration time for this cache item. If expiration doesn't set - nil will be returned.
ExpiresAt() *time.Time
// Sets the expiration time for this cache item.
SetExpiresAt(when time.Time) error
}
Item defines an interface for interacting with objects inside a cache
type CachePool ¶
type CachePool interface {
// Returns cache directory path.
GetDirPath() string
// Returns a Cache Item representing the specified key.
GetItem(key string) CacheItem
// Confirms if the cache contains specified cache item.
HasItem(key string) bool
// Deletes all items in the pool.
Clear() (bool, error)
// Removes the item from the pool.
DeleteItem(key string) (bool, error)
// Put a cache item with expiring time.
Put(key string, from io.Reader, expiresAt time.Time) (CacheItem, error)
// Put a cache item without expiring time.
PutForever(key string, from io.Reader) (CacheItem, error)
}
Pool generates CacheItemInterface objects
type Error ¶
type Item ¶
type Item struct {
Pool CachePool
// contains filtered or unexported fields
}
func (*Item) ExpiresAt ¶
ExpiresAt returns the expiration time for this cache item. If expiration doesn't set - nil will be returned. Important notice: returned time will be WITHOUT nanoseconds (just milliseconds).
func (*Item) Get ¶
Get retrieves the value of the item from the cache associated with this object's key.
func (*Item) GetFilePath ¶
GetFilePath returns path to the associated file.
func (*Item) IsExpired ¶
Indicates if cache item expiration time is exceeded. If expiration data was not set - error will be returned.
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
func (*Pool) DeleteItem ¶
DeleteItem removes the item from the pool.
func (*Pool) GetDirPath ¶
GetDirPath returns cache directory path.
Source Files
Directories