bitbutt

README

bitbutt - a Go implementation of bitcask

bitbutt is a Go implementation of bitcask, a log-structured hash table for fast key/value data.

Etymology

A butt is a type of English beer cask of a specific size. It is equal to half a tun, two hogsheads, three barrels, or 108 imperial gallons, which is the same as 491 litres.

Installation

Installation is as simple as

go get github.com/akrennmair/bitbutt

Documentation

As with all Go packages, you can find the documentation on godoc.org.

For the concepts of bitcask, please refer to the original paper by Basho.

License

See the file LICENSE for license information.

Documentation

Overview

Package bitbutt implements a key-value store based on Basho's bitcask log-structured hash-table.

Index

• Constants
• type BitButt
  • func Open(directory string, opts ...Option) (*BitButt, error)
  • func (b *BitButt) AllKeys() (<-chan []byte, error)
  • func (b *BitButt) Begin() *Tx
  • func (b *BitButt) Close()
  • func (b *BitButt) Delete(key []byte) error
  • func (b *BitButt) Get(key []byte) ([]byte, error)
  • func (b *BitButt) Merge() error
  • func (b *BitButt) Put(key []byte, value []byte) error
  • func (b *BitButt) Sync() error
• type MergeWindow
• type Option
  • func AllowedMergeWindow(window *MergeWindow) Option
  • func DirPerms(perm os.FileMode) Option
  • func FilePerms(perm os.FileMode) Option
  • func ReadOnly() Option
  • func SizeThreshold(size uint64) Option
  • func SyncInterval(interval time.Duration) Option
  • func SyncOnPut() Option
• type Tx
  • func (t *Tx) Commit() error
  • func (t *Tx) Delete(key []byte) error
  • func (t *Tx) Get(key []byte) ([]byte, error)
  • func (t *Tx) Put(key, value []byte) error
  • func (t *Tx) Rollback() error

Constants

const (
	// KiB is to be used with ThresholdSize to specify kibibytes (1024 bytes).
	KiB uint64 = 1024
	// MiB is to be used with ThresholdSize to specify mibibytes (1024 kibibytes).
	MiB = 1024 * KiB
	// GiB is to be used with ThresholdSize to specify gibibytes (1024 mibibytes).
	GiB = 1024 * MiB

	// DefaultSize is the default threshold size.
	DefaultSize = 2 * GiB
)

Types

type BitButt

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

BitButt implements a key-value store based on Basho's bitcask log-structured hash-table.

func Open

func Open(directory string, opts ...Option) (*BitButt, error)

Open opens a bitbutt key-value store, found in directory. If directory doesn't exist yet, it is created. It returns a BitButt object, or an error if opening and loading the key-value store failed.

func (*BitButt) AllKeys

func (b *BitButt) AllKeys() (<-chan []byte, error)

AllKeys returns a channel from which all keys within the bitbutt can be received. It returns an error if there was a problem retrieving the keys.

func (*BitButt) Begin

func (b *BitButt) Begin() *Tx

Begin starts a new transaction.

func (*BitButt) Close

func (b *BitButt) Close()

Close creates missing hint files, closes all open data files, and invalidates the BitButt object.

func (*BitButt) Delete

func (b *BitButt) Delete(key []byte) error

Delete deletes the record identified by key. If the delete operation fails, it returns an error.

func (*BitButt) Get

func (b *BitButt) Get(key []byte) ([]byte, error)

Get returns the stored value for the specified key, or an error if the key-value pair doesn't exist or there was another error when retrieving the value.

func (*BitButt) Merge

func (b *BitButt) Merge() error

Merge merges existing data files if more than one (in addition to the currently active file) exist.

func (*BitButt) Put

func (b *BitButt) Put(key []byte, value []byte) error

Put stores the specified key-value pair in the bitbutt data store. It returns an error if the Put call failed.

func (*BitButt) Sync

func (b *BitButt) Sync() error

Sync calls fsync(2) on the latest data file.

type MergeWindow

type MergeWindow struct {
	StartHour int
	EndHour   int
}

MergeWindow specifies the time window when automatic merges will be conducted.

var (

	// Never is the default MergeWindow: never merge automatically
	Never *MergeWindow

	// Always is the merge window to always merge automatically
	Always = &MergeWindow{0, 23}
)

type Option

type Option func(*BitButt)

Option is a data type to set options when calling Open.

func AllowedMergeWindow

func AllowedMergeWindow(window *MergeWindow) Option

AllowedMergeWindow sets a merge window. If a merge window other than Never is set, merges will be conducted regularly and automatically within that timeframe.

func DirPerms

func DirPerms(perm os.FileMode) Option

DirPerms overrides the default permissions to create directories.

func FilePerms

func FilePerms(perm os.FileMode) Option

FilePerms overrides the default permissions to create files.

func ReadOnly

func ReadOnly() Option

ReadOnly sets a bitbutt store to be opened as read-only.

func SizeThreshold

func SizeThreshold(size uint64) Option

SizeThreshold sets the size threshold when a bitbutt store shall create a new data file.

func SyncInterval

func SyncInterval(interval time.Duration) Option

SyncInterval makes a bitbutt store repeatedy call fsync(2) at a specified interval.

func SyncOnPut

func SyncOnPut() Option

SyncOnPut makes a bitbutt store call fsync(2) on every Put call.

type Tx

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

Tx is a transaction.

A transaction must always be ended with a call to either Commit or Rollback. After a Commit or Rollback, all operations on the transaction return an error.

func (*Tx) Commit

func (t *Tx) Commit() error

Commit commits the transaction. It returns an error if there is an update conflict (i.e. at least one of the keys updated in the current transaction has been updated since the start of the transaction) or if the write to the bitbutt data file fails.

func (*Tx) Delete

func (t *Tx) Delete(key []byte) error

Delete marks the record identified by key for deletion. It takes key-value pairs that were set or updated in the current transaction into account.

func (*Tx) Get

func (t *Tx) Get(key []byte) ([]byte, error)

Get returns the stored value of the specified key. It takes key-value pairs that were updated in the current transaction into account.

func (*Tx) Put

func (t *Tx) Put(key, value []byte) error

Put stores the specified key-value pair for update in the transaction.

func (*Tx) Rollback

func (t *Tx) Rollback() error

Rollback discards all changes of the current transaction.