storage

Documentation

Overview

Package storage implements support for the file format of add. Open or create a database file with storage.Open / storage.Create respectively.

Index

• Constants
• type Config
  • func (c Config) GetString(key string) (string, error)
  • func (c Config) SetString(key, value string) error
• type DBFile
  • func Create(file afero.File, opts ...Option) (*DBFile, error)
  • func Open(file afero.File, opts ...Option) (*DBFile, error)
  • func (db *DBFile) AllocateNewPage() (page.ID, error)
  • func (db *DBFile) Cache() cache.Cache
  • func (db *DBFile) Close() error
  • func (db *DBFile) Closed() bool
  • func (db *DBFile) Config() Config
• type Error
  • func ErrNoSuchCell(cellKey string) Error
  • func (e Error) Error() string
• type Option
  • func WithCacheSize(size int) Option
  • func WithLogger(log zerolog.Logger) Option
• type PageManager
  • func NewPageManager(file afero.File) (*PageManager, error)
  • func (m *PageManager) AllocateNew() (*page.Page, error)
  • func (m *PageManager) Close() error
  • func (m *PageManager) ReadPage(id page.ID) (*page.Page, error)
  • func (m *PageManager) WritePage(p *page.Page) error
• type Validator
  • func NewValidator(file afero.File) *Validator
  • func (v *Validator) Validate() error

Constants

const (
	// DefaultCacheSize is the default amount of pages, that the cache can hold
	// at most. Current limit is 256, which, regarding the current page size of
	// 16K, means, that the maximum size that a full cache will occupy, is 4M
	// (CacheSize * page.Size).
	DefaultCacheSize = 1 << 8

	// HeaderPageID is the page ID of the header page of the database file.
	HeaderPageID page.ID = 0

	// HeaderTables is the string key for the header page's cell "tables"
	HeaderTables = "tables"
	// HeaderPageCount is the string key for the header page's cell "pageCount"
	HeaderPageCount = "pageCount"
	// HeaderConfig is the string key for the header page's cell "config"
	HeaderConfig = "config"
)

const (
	// Version is the storage version that is currently implemented.
	Version = 1
)

Types

type Config

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

Config is an intermediate layer to interact with configuration keys and values of a database file. It holds a pointer to the database file, so this struct may be copied and re-used.

func (Config) GetString

func (c Config) GetString(key string) (string, error)

GetString returns the value associated with the given key, or an error, if there is no such value.

func (Config) SetString

func (c Config) SetString(key, value string) error

SetString associates the given value with the given key. If there already is such a key present in the config, the value will be overwritten.

type DBFile

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

DBFile is a database file that can be opened or created. From this file, you can obtain a page cache, which you must use for reading pages.

func Create

func Create(file afero.File, opts ...Option) (*DBFile, error)

Create creates a new database in the given file with the given options. The file must exist, but be empty and must be a regular file.

func Open

func Open(file afero.File, opts ...Option) (*DBFile, error)

Open opens and validates a given file and creates a (*DBFile) with the given options. If the validation fails, an error explaining the failure will be returned.

func (*DBFile) AllocateNewPage

func (db *DBFile) AllocateNewPage() (page.ID, error)

AllocateNewPage allocates and immediately persists a new page in secondary storage. This will fail if the DBFile is closed. After this method returns, the allocated page can immediately be found by the cache (it is not loaded yet), and you can use the returned page ID to load the page through the cache.

func (*DBFile) Cache

func (db *DBFile) Cache() cache.Cache

Cache returns the cache implementation, that you must use to obtain pages. This will fail if the DBFile is closed.

func (*DBFile) Close

func (db *DBFile) Close() error

Close will close the underlying cache, as well as page manager, as well as the file. Everything will be closed after writing the config and header page.

func (*DBFile) Closed

func (db *DBFile) Closed() bool

Closed indicates, whether this file was closed.

func (*DBFile) Config

func (db *DBFile) Config() Config

Config returns an intermediate layer to interact with the keys and values stored in the config page of the database file. The returned struct may be copied and re-used.

type Error

type Error string

Error is a sentinel error.

const (
	ErrClosed          Error = "already closed"
	ErrNoSuchConfigKey Error = "no such configuration key"
)

Sentinel errors.

func ErrNoSuchCell

func ErrNoSuchCell(cellKey string) Error

ErrNoSuchCell returns an error that indicates, that a cell with the given name could not be found.

func (Error) Error

func (e Error) Error() string

type Option

type Option func(*DBFile)

Option is an option that can is applied to a DBFile on creation.

func WithCacheSize

func WithCacheSize(size int) Option

WithCacheSize specifies a cache size for the DBFile.

func WithLogger

func WithLogger(log zerolog.Logger) Option

WithLogger specifies a logger for the DBFile.

type PageManager

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

PageManager is a manager that is responsible for reading pages from and writing pages to secondary storage. It also can allocate new pages, which will immediately be written to secondary storage.

func NewPageManager

func NewPageManager(file afero.File) (*PageManager, error)

NewPageManager creates a new page manager over the given file. It is assumed, that the file passed validation by a (*storage.Validator).

func (*PageManager) AllocateNew

func (m *PageManager) AllocateNew() (*page.Page, error)

AllocateNew will allocate a new page and immediately persist it in secondary storage. It is guaranteed, that after this call returns, the page is present on disk.

func (*PageManager) Close

func (m *PageManager) Close() error

Close will sync the file with secondary storage and then close it. If syncing fails, the file will not be closed, and an error will be returned.

func (*PageManager) ReadPage

func (m *PageManager) ReadPage(id page.ID) (*page.Page, error)

ReadPage returns the page with the given ID, or an error if reading is impossible.

func (*PageManager) WritePage

func (m *PageManager) WritePage(p *page.Page) error

WritePage will write the given page into secondary storage. It is guaranteed, that after this call returns, the page is present on disk.

type Validator

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

Validator can be used to validate a database file prior to opening it. If validation fails, a speaking error is returned. If validation does not fail, the file is a valid database file and can be used. Valid means, that the file is not structurally corrupted and usable.

func NewValidator

func NewValidator(file afero.File) *Validator

NewValidator creates a new validator over the given file.

func (*Validator) Validate

func (v *Validator) Validate() error

Validate runs the file validation and returns a speaking error on why the validation failed, if it failed.