Skip to main content

structs.go

structs.go - Overview​

This file defines the core data structures used for storing and retrieving data within the Badger key-value store. It includes definitions for value pointers, headers, and entries, along with methods for encoding and decoding these structures for efficient storage and retrieval.

Detailed Documentation​

valuePointer​

type valuePointer struct {
	Fid    uint32
	Len    uint32
	Offset uint32
}
  • Purpose: Represents a pointer to a value stored in the value log. It contains the file ID, length, and offset of the value.
    • Fid: File ID of the value log file.
    • Len: Length of the value.
    • Offset: Offset of the value within the file.

vptrSize​

const vptrSize = unsafe.Sizeof(valuePointer{})
  • Purpose: Defines the size in bytes of the valuePointer struct.

Less​

func (p valuePointer) Less(o valuePointer) bool
  • Purpose: Compares two valuePointer instances.
  • Parameters:
    • o (valuePointer): The other valuePointer to compare with.
  • Returns: bool: Returns true if p is less than o, based on Fid, Offset and Len.

IsZero​

func (p valuePointer) IsZero() bool
  • Purpose: Checks if the valuePointer is a zero value (all fields are zero).
  • Returns: bool: Returns true if all fields (Fid, Offset, Len) are zero.

Encode​

func (p valuePointer) Encode() []byte
  • Purpose: Encodes the valuePointer into a byte slice.
  • Returns: []byte: A byte slice containing the encoded valuePointer.

Decode​

func (p *valuePointer) Decode(b []byte)
  • Purpose: Decodes a byte slice into the valuePointer.
  • Parameters:
    • b ([]byte): The byte slice to decode.
type header struct {
	klen      uint32
	vlen      uint32
	expiresAt uint64
	meta      byte
	userMeta  byte
}
  • Purpose: Represents the header of an entry in the value log.
    • klen: Key length.
    • vlen: Value length.
    • expiresAt: Unix timestamp indicating when the entry expires.
    • meta: Meta data.
    • userMeta: User meta data.

maxHeaderSize​

const (
	// Maximum possible size of the header. The maximum size of header struct will be 18 but the
	// maximum size of varint encoded header will be 22.
	maxHeaderSize = 22
)
  • Purpose: Defines the maximum possible size of the header in bytes.

Encode​

func (h header) Encode(out []byte) int
  • Purpose: Encodes the header into a byte slice.
  • Parameters:
    • out ([]byte): The byte slice to write the encoded header to. Must be at least 5 bytes long.
  • Returns: int: The number of bytes written to the output slice.

Decode​

func (h *header) Decode(buf []byte) int
  • Purpose: Decodes the header from a byte slice.
  • Parameters:
    • buf ([]byte): The byte slice containing the encoded header.
  • Returns: int: The number of bytes read from the byte slice.

DecodeFrom​

func (h *header) DecodeFrom(reader *hashReader) (int, error)
  • Purpose: Decodes the header from a hashReader.
  • Parameters:
    • reader (*hashReader): The hashReader to read the header from.
  • Returns:
    • int: The number of bytes read from the reader.
    • error: An error, if any.

Entry​

type Entry struct {
	Key       []byte
	Value     []byte
	ExpiresAt uint64 // time.Unix
	version   uint64
	offset    uint32 // offset is an internal field.
	UserMeta  byte
	meta      byte

	// Fields maintained internally.
	hlen         int // Length of the header.
	valThreshold int64
}
  • Purpose: Represents a key-value entry.
    • Key: The key.
    • Value: The value.
    • ExpiresAt: Unix timestamp indicating when the entry expires.
    • version: Version of the entry.
    • offset: Offset of the entry in the value log.
    • UserMeta: User-defined metadata.
    • meta: Internal metadata.
    • hlen: Length of the header.
    • valThreshold: Threshold for value size to determine if value is stored inline or in value log.

isZero​

func (e *Entry) isZero() bool
  • Purpose: Checks if the entry is a zero value (key is empty).
  • Returns: bool: Returns true if the key is empty.

estimateSizeAndSetThreshold​

func (e *Entry) estimateSizeAndSetThreshold(threshold int64) int64
  • Purpose: Estimates the size of the entry and sets the value threshold.
  • Parameters:
    • threshold (int64): The threshold value.
  • Returns: int64: The estimated size of the entry.

skipVlogAndSetThreshold​

func (e *Entry) skipVlogAndSetThreshold(threshold int64) bool
  • Purpose: Determines if the value should be skipped from the value log based on its size and sets the value threshold.
  • Parameters:
    • threshold (int64): The threshold value.
  • Returns: bool: True if the value length is less than the threshold.

print​

func (e Entry) print(prefix string)
  • Purpose: Prints the entry's key, meta, userMeta, offset and value's length.
  • Parameters:
    • prefix (string): The prefix to add to the print.

NewEntry​

func NewEntry(key, value []byte) *Entry
  • Purpose: Creates a new Entry with the given key and value.
  • Parameters:
    • key ([]byte): The key for the entry.
    • value ([]byte): The value for the entry.
  • Returns: *Entry: A pointer to the newly created entry.

WithMeta​

func (e *Entry) WithMeta(meta byte) *Entry
  • Purpose: Sets the user meta data for the entry.
  • Parameters:
    • meta (byte): The user meta data.
  • Returns: *Entry: A pointer to the entry with the updated user meta data.

WithDiscard​

func (e *Entry) WithDiscard() *Entry
  • Purpose: Sets the discard earlier versions bit for the entry.
  • Returns: *Entry: A pointer to the entry with the discard bit set.

WithTTL​

func (e *Entry) WithTTL(dur time.Duration) *Entry
  • Purpose: Sets the time-to-live (TTL) for the entry.
  • Parameters:
    • dur (time.Duration): The duration for which the entry should live.
  • Returns: *Entry: A pointer to the entry with the updated expiration time.

withMergeBit​

func (e *Entry) withMergeBit() *Entry
  • Purpose: Sets the merge bit in the entry's metadata.
  • Returns: *Entry: A pointer to the entry with the merge bit set.

Code Examples​

Encoding and Decoding a valuePointer​

// Example of encoding and decoding a valuePointer
const pointer = { Fid: 1, Len: 100, Offset: 50 };
const encoded = new valuePointer(pointer.Fid, pointer.Len, pointer.Offset).Encode();
const decoded = new valuePointer(0, 0, 0);
decoded.Decode(encoded);
// decoded now contains the same values as pointer

Getting Started Relevance​