fscache

README

go-fscache

Cache that uses the filesystem as its keys

Documentation

Overview

Cache that uses the filesystem for indexing keys.

Prefer running on case-sensitive filesystems; running on a case-insensitive one has the side-effect that keys are also case-insensitive.

Index

• Constants
• func Stringify(stuff ...CacheKey) []string
• type CacheDir
  • func NewCacheDir(path string) (cd *CacheDir, err error)
  • func (cd *CacheDir) Chtime(t time.Time, key ...CacheKey) (err error)
  • func (cd *CacheDir) ChtimeNoLock(t time.Time, key ...CacheKey) (err error)
  • func (cd *CacheDir) Create(key ...CacheKey) (fh *os.File, err error)
  • func (cd *CacheDir) Delete(key ...CacheKey) (err error)
  • func (cd *CacheDir) DeleteAll(key ...CacheKey) (err error)
  • func (cd *CacheDir) Get(v interface{}, key ...CacheKey) (mtime time.Time, err error)
  • func (cd *CacheDir) GetAndExpire(v interface{}, max time.Duration, key ...CacheKey) (mtime time.Time, expired bool, err error)
  • func (cd *CacheDir) GetCacheDir() string
  • func (cd *CacheDir) GetCompressionLevel() int
  • func (cd *CacheDir) GetInvalid(key ...CacheKey) (ts time.Time)
  • func (cd *CacheDir) IsValid(maxDuration time.Duration, key ...CacheKey) bool
  • func (cd *CacheDir) Lock(key ...CacheKey) (lock.FileLock, error)
  • func (cd *CacheDir) Open(key ...CacheKey) (fh *os.File, err error)
  • func (cd *CacheDir) OpenFlags(flags int, key ...CacheKey) (fh *os.File, err error)
  • func (cd *CacheDir) Set(v interface{}, key ...CacheKey) (n int64, err error)
  • func (cd *CacheDir) SetCacheDir(path string) (err error)
  • func (cd *CacheDir) SetCompressionLevel(level int)
  • func (cd *CacheDir) SetInvalid(key ...CacheKey) error
  • func (cd *CacheDir) Stat(key ...CacheKey) (stat os.FileInfo, err error)
  • func (cd *CacheDir) Touch(key ...CacheKey) (err error)
  • func (cd *CacheDir) UnsetInvalid(key ...CacheKey) error
• type CacheKey

Constants

const DefaultCompressionLevel = gzip.BestCompression

The default compression level of new CacheDir objects.

Functions

func Stringify

func Stringify(stuff ...CacheKey) []string

Types

type CacheDir

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

func NewCacheDir

func NewCacheDir(path string) (cd *CacheDir, err error)

Creates (or opens) a CacheDir using the given path.

func (*CacheDir) Chtime

func (cd *CacheDir) Chtime(t time.Time, key ...CacheKey) (err error)

Sets the mtime of the file backing the given key to the specified time.

func (*CacheDir) ChtimeNoLock

func (cd *CacheDir) ChtimeNoLock(t time.Time, key ...CacheKey) (err error)

Same as Chtime, but does not try to acquire a file lock on the file before. Only call this if you already hold a lock to the file.

func (*CacheDir) Create

func (cd *CacheDir) Create(key ...CacheKey) (fh *os.File, err error)

Creates a new file to back the specified key.

func (*CacheDir) Delete

func (cd *CacheDir) Delete(key ...CacheKey) (err error)

Deletes the file that backs the specified key.

func (*CacheDir) DeleteAll

func (cd *CacheDir) DeleteAll(key ...CacheKey) (err error)

Deletes the specified key and all subkeys.

func (*CacheDir) Get

func (cd *CacheDir) Get(v interface{}, key ...CacheKey) (mtime time.Time, err error)

Gets the requested key from the cache. The given interface{} must be a pointer or otherwise be modifiable; otherwise Get will panic.

func (*CacheDir) GetAndExpire

func (cd *CacheDir) GetAndExpire(v interface{}, max time.Duration, key ...CacheKey) (mtime time.Time, expired bool, err error)

Calls Get to retrieve the requested key from the cache.

If the key is expired, then it is removed from the cache.

func (*CacheDir) GetCacheDir

func (cd *CacheDir) GetCacheDir() string

Gets the path to the cache directory.

func (*CacheDir) GetCompressionLevel

func (cd *CacheDir) GetCompressionLevel() int

Retrieves the current gzip compression level.

func (*CacheDir) GetInvalid

func (cd *CacheDir) GetInvalid(key ...CacheKey) (ts time.Time)

Returns the time the given key was marked as invalid. If the key is valid, then calling IsZero() on the returned time will return true.

func (*CacheDir) IsValid

func (cd *CacheDir) IsValid(maxDuration time.Duration, key ...CacheKey) bool

Checks if the given key is not marked as invalid, or if it is, checks if it was marked more than maxDuration time ago.

Calls UnsetInvalid if the keys are valid.

func (*CacheDir) Lock

func (cd *CacheDir) Lock(key ...CacheKey) (lock.FileLock, error)

Locks the file that backs the given key.

If the call is successful, it's the caller's responsibility to call Unlock on the returned lock.

func (*CacheDir) Open

func (cd *CacheDir) Open(key ...CacheKey) (fh *os.File, err error)

Opens the file that backs the specified key.

func (*CacheDir) OpenFlags

func (cd *CacheDir) OpenFlags(flags int, key ...CacheKey) (fh *os.File, err error)

Opens the file that backs the specified key using os.OpenFile.

The permission bits are always 0666, which then get filtered by umask.

func (*CacheDir) Set

func (cd *CacheDir) Set(v interface{}, key ...CacheKey) (n int64, err error)

Stores the given interface{} in the cache. Returns the size of the resulting file and the error, if any.

Compresses the resulting data using gzip with the compression level set by SetCompressionLevel().

func (*CacheDir) SetCacheDir

func (cd *CacheDir) SetCacheDir(path string) (err error)

Sets the directory that will back this cache.

Will try to os.MkdirAll the given path; if that fails, then the CacheDir is not modified.

func (*CacheDir) SetCompressionLevel

func (cd *CacheDir) SetCompressionLevel(level int)

func (*CacheDir) SetInvalid

func (cd *CacheDir) SetInvalid(key ...CacheKey) error

Deletes the given key and caches it as invalid.

func (*CacheDir) Stat

func (cd *CacheDir) Stat(key ...CacheKey) (stat os.FileInfo, err error)

Calls os.Stat() on the file or folder that backs the given key.

func (*CacheDir) Touch

func (cd *CacheDir) Touch(key ...CacheKey) (err error)

Updates the mtime of the file backing the given key.

Creates an empty file if it doesn't exist.

func (*CacheDir) UnsetInvalid

func (cd *CacheDir) UnsetInvalid(key ...CacheKey) error

Removes the given key from the invalid key cache.

type CacheKey

type CacheKey interface{}

An arbitrary object that can be stringified by fmt.Sprint().

The stringification is filtered to ensure it doesn't contain characters that are invalid on Windows, which has the most restrictive filesystem. The "bad" characters (\, /, :, *, ?, ", <, >, |) are replaced with _.

On a list of CacheKeys, the last component is taken to represent a file and all the other components represent the intermediary directories. This means that it's not possible to have subkeys of an existing file key.

NOTE: when running on Windows, directories that start with a '.' get the '.' replaced by a '_'. This is because regular Windows tools can't deal with directories starting with a dot.