README
¶
Bitcask
An implementation of the Bitcask paper from Riak. The result is a high-performance key-value store utilizing an on-disk write-ahead log (WAL) for persistence.
Note: Aspects of this are still under development. See TODO/FIXME comments and TODO.md for and idea of what's not yet done and what is planned.
Documentation
¶
Overview ¶
Package bitcask implements a high-performance key-value store utilizing an on-disk write-ahead log (WAL) for persistence, à la the Bitcask paper from Riak.
Index ¶
- Variables
- type Config
- type DB
- func (db *DB) Close() error
- func (db *DB) CompactLog() (bool, error)
- func (db *DB) Delete(key string) error
- func (db *DB) EachKey(f func(key string) bool) error
- func (db *DB) Get(key string) ([]byte, error)
- func (db *DB) Put(key string, value []byte) error
- func (db *DB) PutWithTTL(key string, value []byte, ttl time.Duration) error
- func (db *DB) RotateSegment() error
- func (db *DB) Sync() error
- type LogCompactionError
Constants ¶
This section is empty.
Variables ¶
var ( ErrKeyTooLarge = errors.New("key exceeds configured maximum size") ErrValueTooLarge = errors.New("value exceeds configured maximum size") ErrKeyNotFound = errors.New("key not found") ErrPartialWrite = errors.New("partial write") ErrDatabaseReadOnly = errors.New("database read-only") ErrDatabaseLocked = errors.New("database locked") ErrDatabaseClosed = errors.New("database closed") )
var ( ErrRecordExpired = errors.New("record expired") ErrCorruptRecord = errors.New("corrupt record") )
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// MaxKeySize specifies the maximum key size, in bytes, that may be written
// to the database. Keys of larger size that exist in the database before
// opening may still be read. If <= 0, the max key size is 1024 (1 KiB).
MaxKeySize int
// MaxValueSize specifies the maximum value size, in bytes, that may be
// written to the database. Values of larger size that exist in the database
// before opening may still be read. If <= 0, the max value size is
// 536870912 (512 MiB).
MaxValueSize int
// MaxSegmentSize specifies the maximum segment size, in bytes. If <= 0, the
// max segment size is 4294967296 (4 GiB).
//
// Writes are routed to a new active segment and log compaction is triggered
// (unless [Config.DisableAutomaticLogCompaction] is true) before the active
// segment exceeds this size. Setting this to a value larger than available
// disk space effectively turns off automatic active segment rotation and
// log compaction, in which case both can be performed manually via
// [DB.RotateSegment] and [DB.CompactLog].
//
// It must be at least 20 bytes larger than the sum of [Config.MaxKeySize]
// and [Config.MaxValueSize] in order to accomodate the maximum size WAL
// record.
MaxSegmentSize int64
// DisableAutomaticLogCompaction turns off automatic log compaction when
// true, requiring any log compaction to be triggered manually via
// [DB.CompactLog]. This allows applications to schedule log compaction for
// times when the potential memory and/or CPU usage increase is acceptable,
// such as during off-peak hours.
//
// When false, log compaction runs automatically before the active segment
// exceeds [Config.MaxSegmentSize].
DisableAutomaticLogCompaction bool
// UseStandardMutex mandates the usage of a standard mutex for
// synchronization when true. A reader-writer lock is used when false.
//
// A standard mutex may outperform a reader-writer lock in a surprising
// number of scenarios due to the additional overhead associated with
// reader-writer locks. Users are encouraged to perform their own benchmarks
// to determine which is most appropriate for their use case.
UseStandardMutex bool
// HandleEvent handles emitted events, such as when a log compaction has
// begun, succeeded, or failed. When nil, all events are dropped.
HandleEvent func(event any)
}
Config configures a DB.
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB implements a high-performance, persistent key-value store. It is safe for concurrent use.
func Open ¶
Open returns a DB using the directory at path to load and store data. If no such directory exists, it is created, along with any necessary parent directories.
Subsequent calls to Open by this or any other process before calling DB.Close will result in an ErrDatabaseLocked error as only one DB instance may run against the directory given by path at any moment. TODO: Call os.Sync on DB directory parent dir?
func (*DB) Close ¶
Close closes the database. It syncs the active segment, closes all open file handles, and releases it's lock on the database directory. It blocks until log compaction has completed if one is running at the time.
Once Close has been called on a DB, it may not be reused; future calls to Close or other methods such as DB.Get or DB.Put will return ErrDatabaseClosed.
func (*DB) CompactLog ¶
CompactLog runs log compaction unless already underway or the DB is closed. If a log compaction process is already underway, it returns false and a nil error. If the DB is closed, it returns false and ErrDatabaseClosed. Otherwise, it returns true and any error encountered, blocking until the log compaction process completes.
Unless [Config.DisableAutomaticLogCompaction] is true, log compaction already runs automatically in the background when the active segment reaches the maximum size given by [Config.MaxSegmentSize]. However, this method allows callers to manually trigger a log compaction at will.
func (*DB) EachKey ¶
Keys iterates over all keys, passing each key to f and terminating when f returns false or all keys have been enumerated.
func (*DB) Get ¶
Get gets the value associated with key. ErrKeyNotFound is returned if no such key exists.
func (*DB) Put ¶
Put inserts or overwrites the value associated with key and does not expire. A nil value deletes the key-value pair.
func (*DB) PutWithTTL ¶
PutWithTTL inserts or overwrites the value and time to live (TTL) duration associated with key. The key-value pair expires after the ttl duration elapses. A nil value or TTL duration <= 0 deletes the key-value pair.
func (*DB) RotateSegment ¶
RotateSegment causes the database to begin writing to a new active segment, making the old active segment eligible for compaction.
Active segment rotation already happens automatically when the active segment reaches the maximum size given by [Config.MaxSegmentSize]. However, this method allows callers to manually trigger a rotation at will.
type LogCompactionError ¶
type LogCompactionError struct {
// contains filtered or unexported fields
}
LogCompactionError signifies that log compaction encountered an error. While this means that a full compaction of the log may not have completed, the DB should still be in a consistent state.
func (*LogCompactionError) Error ¶
func (e *LogCompactionError) Error() string
func (*LogCompactionError) Unwrap ¶
func (e *LogCompactionError) Unwrap() error
Source Files