cheapcash

README

Cheapcash

SSD is cheap. Why don't we use it for caching?

A simple library implementing filesystem I/O as a cache. Should be must useful when used again a Solid State Drive for maximum speed and to handle good amount of concurrent read/write.

The API itself is also pretty simple considering I don't want this to be a full-blown caching library like Redis, I just want it to be simple like Bigcache or similar caching library.

Install

import "github.com/aldy505/cheapcash"

Usage

It has simple API for reading & storing cache.

package main

import (
  "log"

  "github.com/aldy505/cheapcash"
)

func main() {
  // Create a Cheapcash instance.
  // Of course you can make multiple instance for multiple
  // root directories.
  cache := cheapcash.New("/tmp/cheapcash")
  // or if you are feeling lazy
  cache = cheapcash.Default()
  // path defaults to /tmp/cheapcash

  err := cache.Write("users:list", usersList)
  if err != nil {
    log.Fatal(err)
  }

  val, err := cache.Read("users:list")
  if err != nil {
    log.Fatal(err)
  }

  log.Println(string(val))

  err = cache.Append("users:list", []byte("\nMarcel"))
  if err != nil {
    log.Fatal(err)
  }

  err = cache.Delete("users:list")
  if err != nil {
    log.Fatal(err)
  }
}

See Godoc documentation (link above, beneath the title) for more complete documentation of the package.

License

MIT

Documentation

Index

• Variables
• type Cache
  • func Default() *Cache
  • func New(path string) *Cache
  • func (c *Cache) Append(key string, value []byte) error
  • func (c *Cache) Delete(key string) error
  • func (c *Cache) Exists(key string) (bool, error)
  • func (c *Cache) Read(key string) ([]byte, error)
  • func (c *Cache) Rename(old, new string) error
  • func (c *Cache) Write(key string, value []byte) error

Variables

var ErrDiskFull = errors.New("there was no space left on the device")

var ErrExists = errors.New("key already exists")

var ErrInvalidPath = errors.New("path supplied is invalid")

var ErrNotExists = errors.New("key does not exist")

Types

type Cache

type Cache struct {
	sync.Mutex
	Path string
}

func Default

func Default() *Cache

Creates default Cheapcash instance which defaults the corresponding cache path to /tmp/cheapcash.

The caveat of using this one is this will be most likely only compatible with UNIX-like filesystem. Windows devices will most likely happen to have an error of the invalid path.

This returns a Cheapcash instance, which method ('Append', 'Exists', 'Write', 'Read') you can do by just specifying the key, without supplying the full path of the cached file.

func New

func New(path string) *Cache

Creates a new Cheapcash instance with the given path from the argument provided.

If path is empty (or an empty string), it will panic with ErrInvalidPath error.

The path provided might have '/' as the ending, so these are valid and will return the same path:

New("/tmp/box")
New("/tmp/box/")

func (*Cache) Append

func (c *Cache) Append(key string, value []byte) error

Directly append a value into an existing key. If a key doesn't exists, it will return an error with a type of ErrNotExists.

c := cheapcash.Default()
err := c.Append("users", []byte("Someone\n"))
if err != nil {
  if errors.Is(err, cheapcash.ErrNotExists) {
    // Handle if file does not exists!
  }
  // Handle any other errors
}

func (*Cache) Delete

func (c *Cache) Delete(key string) error

Delete a key from the cache directory. And of course would return an error of ErrNotExists if the key doesn't exists.

c := cheapcash.Default()
err := c.Write("users", []byte("Someone\n"))
// Handle error here
err = c.Delete("users")
// Handle error here

func (*Cache) Exists

func (c *Cache) Exists(key string) (bool, error)

Check whether or not a key exists. Returns true if the key exists, false otherwise.

WARNING: You should provide your c.Path value yourself.

check, err := cache.Exists("something.txt")
// will search in ./something.txt

check, err = cache.Exists(c.Path + "something.txt")
// will search relative to c.Path value

func (*Cache) Read

func (c *Cache) Read(key string) ([]byte, error)

Read the value of a given key. Will return an error of ErrNotExists if the given key does not exists.

c := cheapcash.Default()
res, err := c.Read("users")
if err != nil {
  // handle your error here!
}
log.Println(string(res))

func (*Cache) Rename

func (c *Cache) Rename(old, new string) error

Rename a key. It's that simple. The contents of the cache stays the same, but the key is renamed.

It will return 2 different error in case of:

1. If the old key (first argument parameter) doesn't exists, it will return an error of ErrNotExists

2. If the new key (second argument parameter) already exists, it will return an error of ErrExists

func (*Cache) Write

func (c *Cache) Write(key string, value []byte) error

Write a key with a value. If the key already exists in the first place, it will delete the existing key and replace it with the new value.

c := cheapcash.Default()
err := c.Write("users", []byte("Someone\n"))
if err != nil {
  // handle your error
}