pagecache

Documentation

Overview

Package pagecache provides the implementation of a caching layer for files implementing the io.ReaderAt interface.

Index

• Constants
• Variables
• type Cache
  • func New(options ...Option) *Cache
  • func NewWithConfig(config *Config) *Cache
  • func (c *Cache) NewFile(id uint32, file io.ReaderAt, size int64) io.ReaderAt
  • func (c *Cache) Stats() (stats Stats)
• type Config
  • func DefaultConfig() *Config
  • func (c *Config) Apply(options ...Option)
• type Option
  • func PageCount(count int64) Option
  • func PageSize(size int64) Option
• type Stats
  • func (s *Stats) HitRate() float64

Constants

const (
	// DefaultPageSize is the default page size used when creating a Cache
	// instance.
	DefaultPageSize = 4096

	// DefaultPageCount is the default page count used when creating a Cache
	// instance.
	DefaultPageCount = 16384
)

Variables

var (
	// ErrNoPages is returned when memory pressure is too high and it is not
	// possible to read files through the page cache.
	ErrNoPages = errors.New("there are no free pages left in the cache")
)

Types

type Cache

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

Cache instances implement the page caching layer of files.

func New

func New(options ...Option) *Cache

New constructs a new Cache instance, using the list of options passed as arguments to configure the cache.

func NewWithConfig

func NewWithConfig(config *Config) *Cache

NewWithConfig is like New but uses a Config instance to pass the cache configuration instead of a list of options.

func (*Cache) NewFile

func (c *Cache) NewFile(id uint32, file io.ReaderAt, size int64) io.ReaderAt

NewFile constructs a wrapper around the file of the given size. id is a unique identifier intended to uniquely represent the file within the cache. If multiple io.ReaderAt interfaces point at the same underlying file, they could share the same id to reference the same pages in the cache.

func (*Cache) Stats

func (c *Cache) Stats() (stats Stats)

Stats returns the current values of cache statistics.

type Config

type Config struct {
	PageSize  int64
	PageCount int64
}

Config carries the configuration for the page cache.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig constructs a new Config instance initialized with the default configuration.

func (*Config) Apply

func (c *Config) Apply(options ...Option)

Apply applies the list of options passed as arguments to c.

type Option

type Option interface {
	Configure(*Config)
}

Option is an interface implemented by options allowing configuration of new Cache instances.

func PageCount

func PageCount(count int64) Option

PageCount is a configuration option setting the number of pages in a Cache instance.

Default: 16384

func PageSize

func PageSize(size int64) Option

PageSize is a cache configuration option setting the size of individual pages in a Cache instance.

If it is not a power of two, the size will be adjusted to the nearest one.

Default: 4 KiB

type Stats

type Stats struct {
	Lookups   int64 // reads from the cache
	Hits      int64 // page reads that were found in the cache
	Inserts   int64 // pages inserted in the cache
	Evictions int64 // pages evicted from the cache
	Allocs    int64 // number of free pages allocated by the cache
	Frees     int64 // number of allocated pages returned to the free pool
}

Stats is a structure carrying statistics collected on cache access.

All counters are absolute values accumulated since a cache instance was created.

func (*Stats) HitRate

func (s *Stats) HitRate() float64

HitRate returns the hit rate of cache lookups, as a floating point value between 0 and 1 (inclusive).