Documentation
¶
Index ¶
- Constants
- Variables
- func DateToTime(d uint32) time.Time
- func NormalizeTTL(t time.Time) time.Time
- func RecordsEqualish(a, b Record) bool
- func TimeToDateDown(t time.Time) uint32
- func TimeToDateUp(t time.Time) uint32
- func WriteTblHeader(fh *os.File, header TblHeader) error
- type Config
- type DB
- type DBStats
- type Expiration
- type HashTbl
- func (h *HashTbl) Close()
- func (h *HashTbl) CompactLoad() float64
- func (h *HashTbl) ComputeEstimates(ctx context.Context) (err error)
- func (h *HashTbl) ExpectOrdered(ctx context.Context) (flush func() error, done func(), err error)
- func (h *HashTbl) Handle() *os.File
- func (h *HashTbl) Header() TblHeader
- func (h *HashTbl) Insert(ctx context.Context, rec Record) (_ bool, err error)
- func (h *HashTbl) Load() float64
- func (h *HashTbl) LogSlots() uint64
- func (h *HashTbl) Lookup(ctx context.Context, key Key) (_ Record, _ bool, err error)
- func (h *HashTbl) MaxLoad() float64
- func (h *HashTbl) Range(ctx context.Context, fn func(context.Context, Record) (bool, error)) error
- func (h *HashTbl) Stats() TblStats
- type Key
- type MemTbl
- func (m *MemTbl) Close()
- func (m *MemTbl) CompactLoad() float64
- func (m *MemTbl) ComputeEstimates(ctx context.Context) error
- func (m *MemTbl) ExpectOrdered(ctx context.Context) (commit func() error, done func(), err error)
- func (m *MemTbl) Handle() *os.File
- func (m *MemTbl) Header() TblHeader
- func (m *MemTbl) Insert(ctx context.Context, rec Record) (_ bool, err error)
- func (m *MemTbl) Load() float64
- func (m *MemTbl) LogSlots() uint64
- func (m *MemTbl) Lookup(ctx context.Context, key Key) (rec Record, ok bool, err error)
- func (m *MemTbl) MaxLoad() float64
- func (m *MemTbl) Range(ctx context.Context, cb func(context.Context, Record) (bool, error)) (err error)
- func (m *MemTbl) Stats() TblStats
- type Reader
- func (l *Reader) Close() error
- func (l *Reader) Key() Key
- func (l *Reader) Read(p []byte) (int, error)
- func (l *Reader) ReadAt(p []byte, off int64) (int, error)
- func (l *Reader) Release()
- func (l *Reader) Revive(ctx context.Context) error
- func (l *Reader) Seek(offset int64, whence int) (int64, error)
- func (l *Reader) Size() int64
- func (l *Reader) Trash() bool
- type Record
- type Store
- func (s *Store) Close()
- func (s *Store) Compact(ctx context.Context, ...) (err error)
- func (s *Store) Create(ctx context.Context, key Key, expires time.Time) (w *Writer, err error)
- func (s *Store) Load() float64
- func (s *Store) Loads() (load, compact, max float64)
- func (s *Store) Read(ctx context.Context, key Key) (_ *Reader, err error)
- func (s *Store) ShouldCompact() bool
- func (s *Store) Stats() StoreStats
- type StoreStats
- type TableKind
- type Tbl
- type TblHeader
- type TblStats
- type Writer
Constants ¶
const (
// RecordSize is the size of a serialized record in bytes.
RecordSize = 64
)
Variables ¶
var (
// Error is the class that wraps all errors generated by the
// hashstore package.
Error = errs.Class("hashstore")
// ErrCollision represents collision errors returned while
// committing to the store.
ErrCollision = errs.New("collision detected")
)
Functions ¶
func DateToTime ¶ added in v1.119.2
func DateToTime(d uint32) time.Time
DateToTime returns the earliest time in the day for the given date.
func NormalizeTTL ¶ added in v1.119.2
func NormalizeTTL(t time.Time) time.Time
NormalizeTTL takes a time and returns a time that is an output of DateToTime that is larger than or equal to the input time, for all times before the year 24937. In other words, it rounds up to the closest time representable for a TTL, and rounds down if no such time is possible (i.e. times after year 24937).
func RecordsEqualish ¶
func RecordsEqualish(a, b Record) bool
RecordsEqualish returns true if the records are equalish. Records are equalish if they are equal except for the expires time and checksums.
func TimeToDateDown ¶ added in v1.119.2
func TimeToDateDown(t time.Time) uint32
TimeToDateDown returns a number of days past the epoch that is less than or equal to t.
func TimeToDateUp ¶ added in v1.119.2
func TimeToDateUp(t time.Time) uint32
TimeToDateUp returns a number of days past the epoch that is greater than or equal to t.
func WriteTblHeader ¶ added in v1.124.4
func WriteTblHeader(fh *os.File, header TblHeader) error
WriteTblHeader writes the header page to the file handle.
Types ¶
type Config ¶ added in v1.122.9
type Config struct {
LogsPath string `help:"path to store log files in (by default, it's relative to the storage directory)'" default:"hashstore"`
TablePath string `` /* 156-byte string literal not displayed */
}
Config is the configuration for the hashstore.
func (Config) Directories ¶ added in v1.122.9
func (c Config) Directories(storagePath string) (logsPath string, tablePath string)
Directories returns the full paths to the logs and tables directories.
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB is a database that stores pieces.
func New ¶
func New(
ctx context.Context,
logsPath string, tablePath string, log *zap.Logger,
shouldTrash func(context.Context, Key, time.Time) bool,
lastRestore func(context.Context) time.Time,
) (_ *DB, err error)
New makes or opens an existing database in the directory allowing for nlogs concurrent writes.
func (*DB) Close ¶
func (d *DB) Close()
Close closes down the database and blocks until all background processes have stopped.
func (*DB) Compact ¶ added in v1.119.2
func (d *DB) Compact(ctx context.Context) (err error)
Compact waits for any background compaction to finish and then calls Compact on both stores. After a call to Compact, you can be sure that each Store was fully compacted at least once.
func (*DB) Create ¶
func (d *DB) Create(ctx context.Context, key Key, expires time.Time) (_ *Writer, err error)
Create adds an entry to the database with the given key and expiration time. Close or Cancel must be called on the Writer when done. It is safe to call either of them multiple times.
type DBStats ¶
type DBStats struct {
NumSet uint64 // number of set records.
LenSet memory.Size // sum of lengths in set records.
AvgSet float64 // average size of length of records.
NumTrash uint64 // number of set trash records.
LenTrash memory.Size // sum of lengths in set trash records.
AvgTrash float64 // average size of length of trash records.
NumSlots uint64 // total number of records available.
TableSize memory.Size // total number of bytes in the hash table.
Load float64 // percent of slots that are set.
NumLogs uint64 // total number of log files.
LenLogs memory.Size // total number of bytes in the log files.
NumLogsTTL uint64 // total number of log files with ttl set.
LenLogsTTL memory.Size // total number of bytes in log files with ttl set.
SetPercent float64 // percent of bytes that are set in the log files.
TrashPercent float64 // percent of bytes that are trash in the log files.
Compacting bool // if true, a background compaction is in progress.
Compactions uint64 // total number of compactions that finished on either store.
Active int // which store is currently active
LogsRewritten uint64 // total number of log files attempted to be rewritten.
DataRewritten memory.Size // total number of bytes of data rewritten.
}
DBStats is a collection of statistics about a database.
type Expiration ¶
type Expiration uint32
Expiration is a 23-bit timestamp with a 1-bit flag for trash.
func MaxExpiration ¶
func MaxExpiration(a, b Expiration) Expiration
MaxExpiration returns the larger of two expirations. All expirations with the trash bit set are larger than expirations without the trash bit set. If both have the same trash bit setting, then the larger of the timestamps is returned. An unset expiration is always largest.
func NewExpiration ¶
func NewExpiration(t uint32, trash bool) Expiration
NewExpiration constructs an Expiration from a timestamp and a trash flag.
func (Expiration) Set ¶
func (e Expiration) Set() bool
Set returns true if the expiration is set: not zero.
type HashTbl ¶
type HashTbl struct {
// contains filtered or unexported fields
}
HashTbl is an on disk hash table of records.
func CreateHashtbl ¶
func CreateHashtbl(ctx context.Context, fh *os.File, logSlots uint64, created uint32) (_ *HashTbl, err error)
CreateHashtbl allocates a new hash table with the given log base 2 number of records and created timestamp. The file is truncated and allocated to the correct size.
func OpenHashtbl ¶
func OpenHashtbl(ctx context.Context, fh *os.File) (_ *HashTbl, err error)
OpenHashtbl opens an existing hash table stored in the given file handle.
func (*HashTbl) Close ¶
func (h *HashTbl) Close()
Close closes the hash table and returns when no more operations are running.
func (*HashTbl) CompactLoad ¶ added in v1.125.2
func (h *HashTbl) CompactLoad() float64
CompactLoad returns the load factor the tbl should be compacted at.
func (*HashTbl) ComputeEstimates ¶ added in v1.122.3
func (h *HashTbl) ComputeEstimates(ctx context.Context) (err error)
ComputeEstimates samples the hash table to compute the number of set keys and the total length of the length fields in all of the set records.
func (*HashTbl) ExpectOrdered ¶ added in v1.120.1
func (h *HashTbl) ExpectOrdered(ctx context.Context) (flush func() error, done func(), err error)
ExpectOrdered signals that incoming writes to the hashtbl will be ordered so that a large shared buffer across Insert calls would be effective. This is useful when rewriting a hashtbl during a Compaction, for instance. It returns a flush callback that both flushes any potentially buffered records and disables the expectation. Additionally, Lookups may not find entries written until after the flush callback is called. If flush returns an error there is no guarantee about what records were written. It returns a done callback that discards any potentially buffered records and disables the expectation. At least one of flush or done must be called. It returns an error if called again before flush or done is called.
func (*HashTbl) Handle ¶ added in v1.124.4
func (h *HashTbl) Handle() *os.File
Handle returns the file handle the table was created with.
func (*HashTbl) Header ¶ added in v1.124.4
func (h *HashTbl) Header() TblHeader
Header returns the TblHeader the table was created with.
func (*HashTbl) Insert ¶
func (h *HashTbl) Insert(ctx context.Context, rec Record) (_ bool, err error)
Insert adds a record to the hash table. It returns (true, nil) if the record was inserted, it returns (false, nil) if the hash table is full, and (false, err) if any errors happened trying to insert the record.
func (*HashTbl) Load ¶
func (h *HashTbl) Load() float64
Load returns an estimate of what fraction of the hash table is occupied.
func (*HashTbl) LogSlots ¶ added in v1.124.4
func (h *HashTbl) LogSlots() uint64
LogSlots returns the logSlots the table was created with.
func (*HashTbl) Lookup ¶
func (h *HashTbl) Lookup(ctx context.Context, key Key) (_ Record, _ bool, err error)
Lookup returns the record for the given key if it exists in the hash table. It returns (rec, true, nil) if the record existed, (rec{}, false, nil) if it did not exist, and (rec{}, false, err) if any errors happened trying to look up the record.
func (*HashTbl) MaxLoad ¶ added in v1.125.2
func (h *HashTbl) MaxLoad() float64
MaxLoad returns the load factor at which no more inserts should happen.
type MemTbl ¶ added in v1.125.2
type MemTbl struct {
// contains filtered or unexported fields
}
MemTbl is an in-memory hash table of records with a file for persistence.
func CreateMemtbl ¶ added in v1.125.2
func CreateMemtbl(ctx context.Context, fh *os.File, logSlots uint64, created uint32) (_ *MemTbl, err error)
CreateMemtbl allocates a new mem table with the given log base 2 number of records and created timestamp.
func OpenMemtbl ¶ added in v1.125.2
func OpenMemtbl(ctx context.Context, fh *os.File) (_ *MemTbl, err error)
OpenMemtbl opens an existing hash table stored in the given file handle.
func (*MemTbl) Close ¶ added in v1.125.2
func (m *MemTbl) Close()
Close closes the mem table and returns when no more operations are running.
func (*MemTbl) CompactLoad ¶ added in v1.125.2
func (m *MemTbl) CompactLoad() float64
CompactLoad returns the load factor the tbl should be compacted at.
func (*MemTbl) ComputeEstimates ¶ added in v1.125.2
func (m *MemTbl) ComputeEstimates(ctx context.Context) error
ComputeEstimates doesn't do anything because the memtbl always has exact estimates.
func (*MemTbl) ExpectOrdered ¶ added in v1.125.2
func (m *MemTbl) ExpectOrdered(ctx context.Context) (commit func() error, done func(), err error)
ExpectOrdered signals that incoming writes to the memtbl will be ordered so that a large shared buffer across Insert calls would be effective. This is useful when rewriting a memtbl during a Compaction, for instance. It returns a flush callback that both flushes any potentially buffered records and disables the expectation. Additionally, Lookups may not find entries written until after the flush callback is called. If flush returns an error there is no guarantee about what records were written. It returns a done callback that discards any potentially buffered records and disables the expectation. At least one of flush or done must be called. It returns an error if called again before flush or done is called.
func (*MemTbl) Handle ¶ added in v1.125.2
func (m *MemTbl) Handle() *os.File
Handle returns the file handle the table was created with.
func (*MemTbl) Header ¶ added in v1.125.2
func (m *MemTbl) Header() TblHeader
Header returns the TblHeader the table was created with.
func (*MemTbl) Insert ¶ added in v1.125.2
func (m *MemTbl) Insert(ctx context.Context, rec Record) (_ bool, err error)
Insert adds a record to the mem table. It returns (true, nil) if the record was inserted, it returns (false, nil) if the mem table is full, and (false, err) if any errors happened trying to insert the record.
func (*MemTbl) Load ¶ added in v1.125.2
func (m *MemTbl) Load() float64
Load returns an estimate of what fraction of the mem table is occupied.
func (*MemTbl) LogSlots ¶ added in v1.125.2
func (m *MemTbl) LogSlots() uint64
LogSlots returns the logSlots the table was created with.
func (*MemTbl) Lookup ¶ added in v1.125.2
func (m *MemTbl) Lookup(ctx context.Context, key Key) (rec Record, ok bool, err error)
Lookup returns the record for the given key if it exists in the mem table. It returns (rec, true, nil) if the record existed, (rec{}, false, nil) if it did not exist, and (rec{}, false, err) if any errors happened trying to look up the record.
func (*MemTbl) MaxLoad ¶ added in v1.125.2
func (m *MemTbl) MaxLoad() float64
MaxLoad returns the load factor at which no more inserts should happen.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader is a type that reads a section from a log file.
func (*Reader) Close ¶
func (l *Reader) Close() error
Close is like Release but implements io.Closer. The returned error is always nil.
func (*Reader) ReadAt ¶
func (l *Reader) ReadAt(p []byte, off int64) (int, error)
ReadAt implements io.ReaderAt.
func (*Reader) Release ¶
func (l *Reader) Release()
Release returns the resources associated with the reader. It must be called when done.
func (*Reader) Revive ¶ added in v1.125.2
func (l *Reader) Revive(ctx context.Context) error
Revive attempts to revive a trashed piece.
type Record ¶
type Record struct {
Key Key // 256 bits (32b) of key
Offset uint64 // 48 bits (6b) of offset (256TB max file size)
Log uint64 // 64 bits (8b) of log id (effectively unlimited number of logs)
Length uint32 // 32 bits (4b) of length (4GB max piece size)
Created uint32 // 23 bits (3b) of days since epoch (~22900 years), 1 bit reserved
Expires Expiration // 23 bits (3b) of days since epoch (~22900 years), 1 bit flag for trash
}
Record contains metadata about a piece stored in a hash table.
func (*Record) ReadFrom ¶
func (r *Record) ReadFrom(buf *[RecordSize]byte) bool
ReadFrom updates the record with the values from the buffer and returns true if the checksum is valid.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is a hash table based key-value store with compaction.
func NewStore ¶
func NewStore(ctx context.Context, logsPath string, tablePath string, log *zap.Logger) (_ *Store, err error)
NewStore creates or opens a store in the given directory.
func (*Store) Close ¶
func (s *Store) Close()
Close interrupts any compactions and closes the store.
func (*Store) Compact ¶
func (s *Store) Compact(
ctx context.Context,
shouldTrash func(ctx context.Context, key Key, created time.Time) bool,
lastRestore time.Time,
) (err error)
Compact removes keys and files that are definitely expired, and marks keys that are determined trash by the callback to expire in the future. It also rewrites any log files that have too much dead data.
func (*Store) Create ¶
func (s *Store) Create(ctx context.Context, key Key, expires time.Time) (w *Writer, err error)
Create returns a Handle that writes data to the store. The error on Close must be checked. Expires is when the data expires, or zero if it never expires.
func (*Store) Load ¶
func (s *Store) Load() float64
Load returns the estimated load factor of the hash table. If it's too large, a Compact call is indicated.
func (*Store) Loads ¶ added in v1.125.2
func (s *Store) Loads() (load, compact, max float64)
Loads returns the estimated load factor of the hash table, the load it should be compacted at, and the load that it should no longer be written to.
func (*Store) Read ¶
func (s *Store) Read(ctx context.Context, key Key) (_ *Reader, err error)
Read returns a Reader that reads data from the store. The Reader will be nil if the key does not exist.
func (*Store) ShouldCompact ¶ added in v1.125.2
func (s *Store) ShouldCompact() bool
ShouldCompact returns true if the underlying table indicates that a compaction would be useful.
type StoreStats ¶
type StoreStats struct {
NumLogs uint64 // total number of log files.
LenLogs memory.Size // total number of bytes in the log files.
NumLogsTTL uint64 // total number of log files with ttl set.
LenLogsTTL memory.Size // total number of bytes in log files with ttl set.
SetPercent float64 // percent of bytes that are set in the log files.
TrashPercent float64 // percent of bytes that are trash in the log files.
Compacting bool // if true, a compaction is in progress.
Compactions uint64 // number of compaction calls that finished
TableFull uint64 // number of times the hashtbl was full trying to insert
Today uint32 // the current date.
LastCompact uint32 // the date of the last compaction.
LogsRewritten uint64 // number of log files attempted to be rewritten.
DataRewritten memory.Size // number of bytes rewritten in the log files.
Table TblStats // stats about the hash table.
Compaction struct {
Elapsed float64 // number of seconds elapsed in the compaction
Remaining float64 // estimated number of seconds remaining in the compaction
TotalRecords uint64 // total number of records expected to be processed in the compaction
ProcessedRecords uint64 // total number of records processed in the compaction
}
}
StoreStats is a collection of statistics about a store.
type TableKind ¶ added in v1.125.2
type TableKind byte
TableKind is an enumeration of the different table kinds.
type Tbl ¶ added in v1.124.4
type Tbl interface {
Close()
Handle() *os.File
Stats() TblStats
LogSlots() uint64
Header() TblHeader
CompactLoad() float64
MaxLoad() float64
Load() float64
ComputeEstimates(context.Context) error
ExpectOrdered(context.Context) (func() error, func(), error)
Range(context.Context, func(context.Context, Record) (bool, error)) error
Insert(context.Context, Record) (bool, error)
Lookup(context.Context, Key) (Record, bool, error)
}
Tbl describes a hash table for a store.
func CreateTable ¶ added in v1.125.2
func CreateTable(ctx context.Context, fh *os.File, logSlots uint64, created uint32, kind TableKind) (_ Tbl, err error)
CreateTable creates a new table of the given kind.
type TblHeader ¶ added in v1.124.4
type TblHeader struct {
Created uint32 // when the hashtbl was created
HashKey bool // if we apply a hash function to the key
Kind TableKind // kind of table
LogSlots uint64 // number of expected logslots
}
TblHeader is the header at the start of a hash table.
func ReadTblHeader ¶ added in v1.124.4
func ReadTblHeader(fh *os.File) (header TblHeader, err error)
ReadTblHeader reads the header page from the file handle.
type TblStats ¶ added in v1.124.4
type TblStats struct {
NumSet uint64 // number of set records.
LenSet memory.Size // sum of lengths in set records.
AvgSet float64 // average size of length of records.
NumTrash uint64 // number of set trash records.
LenTrash memory.Size // sum of lengths in set trash records.
AvgTrash float64 // average size of length of trash records.
NumSlots uint64 // total number of records available.
TableSize memory.Size // total number of bytes in the hash table.
Load float64 // percent of slots that are set.
Created uint32 // date that the hashtbl was created.
Kind TableKind // kind of table
}
TblStats contains statistics about a hash table.
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer is a type that allows one to write a piece to a log file.
func (*Writer) Cancel ¶
func (h *Writer) Cancel()
Cancel discards the writes that have happened. Close or Cancel must be called at least once.
func (*Writer) Close ¶
func (h *Writer) Close() (err error)
Close commits the writes that have happened. Close or Cancel must be called at least once.