mvcc

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 22, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package mvcc provides Multi-Version Concurrency Control components for ObaDB.

Package mvcc implements Multi-Version Concurrency Control for the ObaDB storage engine.

Overview

MVCC provides transaction isolation without blocking readers. It enables:

  • Snapshot isolation for consistent reads
  • Non-blocking reads during writes
  • Copy-on-write for safe updates
  • Garbage collection of old versions

Snapshot Isolation

Each transaction sees a consistent snapshot of the database: 

snapshot := mvcc.NewSnapshot(store, txID)

// Read sees data as of snapshot creation
entry, err := snapshot.Get(dn)

// Concurrent writes don't affect this snapshot

Copy-on-Write

Modifications create new versions without modifying existing data: 

cow := mvcc.NewCOW(store)

// Create new version of page
newPageID, err := cow.CopyPage(oldPageID)

// Modify new page (original unchanged)
err = cow.ModifyPage(newPageID, data)

Version Management

Versions are tracked with transaction IDs: 

version := &mvcc.Version{
    TxID:      txID,
    PageID:    pageID,
    CreatedAt: time.Now(),
}

Garbage Collection

Old versions are cleaned up when no longer needed: 

gc := mvcc.NewGC(store)

// Remove versions older than oldest active transaction
gc.Collect(oldestActiveTxID)

Package mvcc provides Multi-Version Concurrency Control for ObaDB.

Package mvcc provides Multi-Version Concurrency Control components for ObaDB.

Package mvcc provides Multi-Version Concurrency Control for ObaDB.

Package mvcc provides Multi-Version Concurrency Control for ObaDB.

Package mvcc provides Multi-Version Concurrency Control for ObaDB. It implements version chains that track multiple versions of each entry, allowing readers to access consistent snapshots while writers create new versions.

Package mvcc provides Multi-Version Concurrency Control for ObaDB.

Index

Constants

View Source 
const DefaultCacheSize = 10000
View Source 
const DefaultGCInterval = 30 * time.Second

DefaultGCInterval is the default interval between GC runs.

View Source 
const VersionHeaderSize = 32

VersionHeader is the serialized header for a version. Layout (32 bytes):

  • Bytes 0-7: TxID (uint64)
  • Bytes 8-15: CommitTS (uint64)
  • Bytes 16-23: PageID (uint64)
  • Bytes 24-25: SlotID (uint16)
  • Byte 26: State (uint8)
  • Bytes 27-31: Reserved

Variables

View Source 
var (
	ErrCoWManagerClosed     = errors.New("CoW manager is closed")
	ErrTransactionNil       = errors.New("transaction is nil")
	ErrTransactionNotActive = errors.New("transaction is not active")
	ErrPageNotFound         = errors.New("page not found")
	ErrCommitFailed         = errors.New("commit failed")
	ErrRollbackFailed       = errors.New("rollback failed")
	ErrWALWriteFailed       = errors.New("failed to write WAL record")
)

CoW manager errors.

View Source 
var (
	ErrGCAlreadyRunning = errors.New("garbage collector is already running")
	ErrGCNotRunning     = errors.New("garbage collector is not running")
	ErrGCClosed         = errors.New("garbage collector is closed")
	ErrEntryNotFound    = errors.New("entry not found")
)

GC errors.

View Source 
var (
	ErrShadowPageNotFound   = errors.New("shadow page not found")
	ErrShadowPageExists     = errors.New("shadow page already exists for this original")
	ErrInvalidShadowMapping = errors.New("invalid shadow page mapping")
	ErrShadowManagerClosed  = errors.New("shadow manager is closed")
)

Shadow page management errors.

View Source 
var (
	ErrSnapshotNotFound = errors.New("snapshot not found")
	ErrSnapshotReleased = errors.New("snapshot has been released")
	ErrInvalidSnapshot  = errors.New("invalid snapshot")
	ErrNilTxManager     = errors.New("transaction manager is nil")
	ErrSnapshotInUse    = errors.New("snapshot is still in use")
)

Snapshot errors.

View Source 
var (
	ErrVersionNotFound    = errors.New("version not found")
	ErrVersionDeleted     = errors.New("version has been deleted")
	ErrNoVisibleVersion   = errors.New("no visible version for snapshot")
	ErrInvalidVersion     = errors.New("invalid version data")
	ErrVersionConflict    = errors.New("version conflict detected")
	ErrNilTransaction     = errors.New("transaction is nil")
	ErrTransactionAborted = errors.New("transaction has been aborted")
)

Version errors.

Functions

func IsVersionVisible 

func IsVersionVisible(version *Version, snapshot *Snapshot) bool

IsVersionVisible is a standalone function that determines version visibility. This can be used without a VisibilityChecker instance.

Types

type CachedEntry 

type CachedEntry struct {
	DN      string
	Version *Version
	PageID  storage.PageID
	SlotID  uint16
}

type CoWManager 

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

CoWManager implements copy-on-write semantics for page modifications. Instead of updating pages in place, modifications create new page versions. This enables lock-free reads and simplifies crash recovery.

CoW workflow: 1. Read: Return original page (no copy needed) 2. Write: Create shadow copy, modify shadow 3. Commit: Update page pointers atomically 4. Rollback: Free shadow pages

func NewCoWManager 

func NewCoWManager(pm *storage.PageManager, txm *tx.TxManager, wal *storage.WAL) *CoWManager

NewCoWManager creates a new CoWManager with the given dependencies.

func (*CoWManager) Close 

func (cow *CoWManager) Close() error

Close closes the CoW manager and releases resources.

func (*CoWManager) CommitPages 

func (cow *CoWManager) CommitPages(txn *tx.Transaction) error

CommitPages commits all shadow pages for the given transaction. This atomically switches page pointers from originals to shadows. The original pages are freed after successful commit.

func (*CoWManager) GetPage 

func (cow *CoWManager) GetPage(txn *tx.Transaction, id storage.PageID) (*storage.Page, error)

GetPage returns the page for reading within the given transaction. For reads, we return the original page if no shadow exists, or the shadow page if the transaction has modified it.

func (*CoWManager) GetPageManager 

func (cow *CoWManager) GetPageManager() *storage.PageManager

GetPageManager returns the underlying page manager.

func (*CoWManager) GetShadowManager 

func (cow *CoWManager) GetShadowManager() *ShadowManager

GetShadowManager returns the underlying shadow manager. This is useful for testing and advanced operations.

func (*CoWManager) ModifyPage 

func (cow *CoWManager) ModifyPage(txn *tx.Transaction, id storage.PageID) (*storage.Page, error)

ModifyPage returns a writable copy of the page for the given transaction. If no shadow exists, it creates one. If a shadow already exists for this transaction, it returns the existing shadow.

func (*CoWManager) RollbackPages 

func (cow *CoWManager) RollbackPages(txn *tx.Transaction) error

RollbackPages rolls back all shadow pages for the given transaction. This frees all shadow pages without modifying the original pages.

func (*CoWManager) ShadowCount 

func (cow *CoWManager) ShadowCount() int

ShadowCount returns the total number of active shadow pages.

func (*CoWManager) TransactionShadowCount 

func (cow *CoWManager) TransactionShadowCount(txID uint64) int

TransactionShadowCount returns the number of shadow pages for a specific transaction.

func (*CoWManager) WriteShadowPage 

func (cow *CoWManager) WriteShadowPage(txn *tx.Transaction, originalID storage.PageID, page *storage.Page) error

WriteShadowPage writes the modified shadow page back to disk. This should be called after modifying the page returned by ModifyPage.

type EntryCache 

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

func NewEntryCache 

func NewEntryCache(maxSize int) *EntryCache

func (*EntryCache) Clear 

func (c *EntryCache) Clear()

func (*EntryCache) Delete 

func (c *EntryCache) Delete(dn string)

func (*EntryCache) Get 

func (c *EntryCache) Get(dn string) *CachedEntry

func (*EntryCache) Len 

func (c *EntryCache) Len() int

func (*EntryCache) Put 

func (c *EntryCache) Put(dn string, version *Version, pageID storage.PageID, slotID uint16)

func (*EntryCache) Stats 

func (c *EntryCache) Stats() (hits, misses uint64)

type GCConfig 

type GCConfig struct {
	// Interval is the time between automatic GC runs.
	Interval time.Duration

	// MinVersionAge is the minimum age of versions before they can be collected.
	// This provides a safety margin to avoid collecting versions that might
	// still be needed by very recent transactions.
	MinVersionAge time.Duration

	// BatchSize is the maximum number of entries to process per GC cycle.
	// 0 means no limit.
	BatchSize int
}

GCConfig holds configuration options for the GarbageCollector.

func DefaultGCConfig 

func DefaultGCConfig() GCConfig

DefaultGCConfig returns the default GC configuration.

type GCStats 

type GCStats struct {
	// TotalRuns is the total number of GC runs.
	TotalRuns uint64

	// TotalVersionsCollected is the total number of versions collected.
	TotalVersionsCollected uint64

	// TotalPagesFreed is the total number of pages freed.
	TotalPagesFreed uint64

	// TotalEntriesProcessed is the total number of entries processed.
	TotalEntriesProcessed uint64

	// LastRunTime is the timestamp of the last GC run.
	LastRunTime time.Time

	// LastRunDuration is the duration of the last GC run.
	LastRunDuration time.Duration

	// LastVersionsCollected is the number of versions collected in the last run.
	LastVersionsCollected int

	// LastPagesFreed is the number of pages freed in the last run.
	LastPagesFreed int
}

GCStats holds statistics about garbage collection.

type GarbageCollector 

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

GarbageCollector reclaims space from old versions that are no longer visible to any active transaction. This prevents unbounded storage growth from MVCC versioning.

GC algorithm: 1. Find oldest active snapshot timestamp 2. For each entry with version chain:

  • Find versions older than the oldest snapshot
  • Remove versions that are no longer visible to any snapshot

3. Free pages containing only garbage 4. Update free list

func NewGarbageCollector 

func NewGarbageCollector(vs *VersionStore, sm *SnapshotManager, pm *storage.PageManager) *GarbageCollector

NewGarbageCollector creates a new GarbageCollector with the given dependencies.

func NewGarbageCollectorWithConfig 

func NewGarbageCollectorWithConfig(vs *VersionStore, sm *SnapshotManager, pm *storage.PageManager, config GCConfig) *GarbageCollector

NewGarbageCollectorWithConfig creates a new GarbageCollector with custom configuration.

func (*GarbageCollector) Close 

func (gc *GarbageCollector) Close() error

Close stops the GC and releases resources.

func (*GarbageCollector) Collect 

func (gc *GarbageCollector) Collect() (int, error)

Collect performs a garbage collection cycle. It identifies and removes old versions that are no longer visible to any active snapshot. Returns the number of pages freed and any error encountered.

func (*GarbageCollector) CollectEntry 

func (gc *GarbageCollector) CollectEntry(dn string) error

CollectEntry performs garbage collection on a specific entry. This is useful for targeted cleanup after deleting an entry.

func (*GarbageCollector) GetConfig 

func (gc *GarbageCollector) GetConfig() GCConfig

GetConfig returns the current GC configuration.

func (*GarbageCollector) GetPageManager 

func (gc *GarbageCollector) GetPageManager() *storage.PageManager

GetPageManager returns the page manager (for testing).

func (*GarbageCollector) GetSnapshotManager 

func (gc *GarbageCollector) GetSnapshotManager() *SnapshotManager

GetSnapshotManager returns the snapshot manager (for testing).

func (*GarbageCollector) GetVersionStore 

func (gc *GarbageCollector) GetVersionStore() *VersionStore

GetVersionStore returns the version store (for testing).

func (*GarbageCollector) IsRunning 

func (gc *GarbageCollector) IsRunning() bool

IsRunning returns true if the background GC is running.

func (*GarbageCollector) SetInterval 

func (gc *GarbageCollector) SetInterval(interval time.Duration)

SetInterval updates the GC interval. This takes effect on the next GC cycle.

func (*GarbageCollector) Start 

func (gc *GarbageCollector) Start() error

Start starts the background garbage collection process. GC runs periodically at the configured interval.

func (*GarbageCollector) Stats 

func (gc *GarbageCollector) Stats() GCStats

Stats returns the current GC statistics.

func (*GarbageCollector) Stop 

func (gc *GarbageCollector) Stop() error

Stop stops the background garbage collection process. It waits for the current GC cycle to complete before returning.

func (*GarbageCollector) TriggerCollect 

func (gc *GarbageCollector) TriggerCollect() (int, error)

TriggerCollect triggers an immediate GC cycle without waiting for the interval. This is useful for testing or when immediate cleanup is needed.

type ShadowManager 

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

ShadowManager manages shadow pages for copy-on-write operations. It tracks which original pages have shadow copies and provides methods to create, lookup, and cleanup shadow pages.

func NewShadowManager 

func NewShadowManager(pm *storage.PageManager) *ShadowManager

NewShadowManager creates a new ShadowManager with the given PageManager.

func (*ShadowManager) ClearTransactionMappings 

func (sm *ShadowManager) ClearTransactionMappings(txID uint64)

ClearTransactionMappings removes the transaction's shadow list without freeing pages. This is typically called after commit when shadows become the new originals.

func (*ShadowManager) Close 

func (sm *ShadowManager) Close() error

Close closes the shadow manager. Note: This does NOT free any shadow pages - they should be cleaned up by the CoW manager before closing.

func (*ShadowManager) CreateShadow 

func (sm *ShadowManager) CreateShadow(txID uint64, originalID storage.PageID) (storage.PageID, error)

CreateShadow creates a shadow copy of the given page for the specified transaction. It allocates a new page, copies the original page's content, and records the mapping. Returns the shadow page ID.

func (*ShadowManager) FreeShadow 

func (sm *ShadowManager) FreeShadow(originalID storage.PageID) error

FreeShadow removes the shadow mapping and frees the shadow page.

func (*ShadowManager) FreeTransactionShadows 

func (sm *ShadowManager) FreeTransactionShadows(txID uint64) error

FreeTransactionShadows frees all shadow pages created by the given transaction. This is typically called during rollback.

func (*ShadowManager) GetAllMappings 

func (sm *ShadowManager) GetAllMappings() map[storage.PageID]storage.PageID

GetAllMappings returns a copy of all current shadow mappings. Key: original PageID, Value: shadow PageID

func (*ShadowManager) GetOriginal 

func (sm *ShadowManager) GetOriginal(shadowID storage.PageID) (storage.PageID, error)

GetOriginal returns the original page ID for the given shadow page ID. Returns ErrShadowPageNotFound if the shadow is not found.

func (*ShadowManager) GetShadow 

func (sm *ShadowManager) GetShadow(originalID storage.PageID) (storage.PageID, error)

GetShadow returns the shadow page ID for the given original page ID. Returns ErrShadowPageNotFound if no shadow exists.

func (*ShadowManager) GetTransactionShadows 

func (sm *ShadowManager) GetTransactionShadows(txID uint64) []storage.PageID

GetTransactionShadows returns all shadow page IDs created by the given transaction.

func (*ShadowManager) HasShadow 

func (sm *ShadowManager) HasShadow(originalID storage.PageID) bool

HasShadow checks if a shadow page exists for the given original page ID.

func (*ShadowManager) RemoveShadow 

func (sm *ShadowManager) RemoveShadow(originalID storage.PageID) error

RemoveShadow removes the shadow mapping for the given original page ID. This does NOT free the shadow page - use FreeShadow for that.

func (*ShadowManager) ShadowCount 

func (sm *ShadowManager) ShadowCount() int

ShadowCount returns the total number of active shadow pages.

func (*ShadowManager) TransactionShadowCount 

func (sm *ShadowManager) TransactionShadowCount(txID uint64) int

TransactionShadowCount returns the number of shadow pages for a specific transaction.

type ShadowMapping 

type ShadowMapping struct {
	OriginalID storage.PageID // The original page ID
	ShadowID   storage.PageID // The shadow (copy) page ID
	TxID       uint64         // Transaction that created this shadow
}

ShadowMapping represents a mapping from an original page to its shadow copy.

type Snapshot 

type Snapshot struct {
	// Timestamp is the logical timestamp when this snapshot was created.
	// Versions with CommitTS <= Timestamp are potentially visible.
	Timestamp uint64

	// ActiveTxIDs contains the IDs of transactions that were active when
	// this snapshot was created. Versions created by these transactions
	// are not visible to this snapshot, even if they commit later.
	ActiveTxIDs []uint64

	// TxID is the transaction ID that owns this snapshot.
	// Used to allow a transaction to see its own uncommitted changes.
	TxID uint64
	// contains filtered or unexported fields
}

Snapshot represents a consistent view of the database at a specific point in time. It captures the state of active transactions at the time of creation to determine version visibility.

func NewSnapshot 

func NewSnapshot(timestamp uint64, activeTxIDs []uint64, txID uint64) *Snapshot

NewSnapshot creates a new snapshot with the given timestamp and active transaction IDs.

func (*Snapshot) AddRef 

func (s *Snapshot) AddRef()

AddRef increments the reference count.

func (*Snapshot) Clone 

func (s *Snapshot) Clone() *Snapshot

Clone creates a copy of the snapshot (for inspection purposes).

func (*Snapshot) GetActiveTxIDs 

func (s *Snapshot) GetActiveTxIDs() []uint64

GetActiveTxIDs returns a copy of the active transaction IDs.

func (*Snapshot) GetTimestamp 

func (s *Snapshot) GetTimestamp() uint64

GetTimestamp returns the snapshot timestamp.

func (*Snapshot) GetTxID 

func (s *Snapshot) GetTxID() uint64

GetTxID returns the transaction ID that owns this snapshot.

func (*Snapshot) IsReleased 

func (s *Snapshot) IsReleased() bool

IsReleased returns true if the snapshot has been released.

func (*Snapshot) RefCount 

func (s *Snapshot) RefCount() int32

RefCount returns the current reference count.

func (*Snapshot) Release 

func (s *Snapshot) Release() bool

Release decrements the reference count and marks as released if count reaches 0. Returns true if the snapshot was actually released (refCount reached 0).

func (*Snapshot) WasActiveAtSnapshot 

func (s *Snapshot) WasActiveAtSnapshot(txID uint64) bool

WasActiveAtSnapshot returns true if the given transaction ID was active when this snapshot was created.

type SnapshotManager 

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

SnapshotManager manages snapshots for MVCC. It tracks the current timestamp, active snapshots, and provides methods to create and release snapshots.

func NewSnapshotManager 

func NewSnapshotManager(txManager *tx.TxManager) *SnapshotManager

NewSnapshotManager creates a new SnapshotManager with the given TxManager.

func (*SnapshotManager) ActiveSnapshotCount 

func (sm *SnapshotManager) ActiveSnapshotCount() int

ActiveSnapshotCount returns the number of active (non-released) snapshots.

func (*SnapshotManager) AdvanceTimestamp 

func (sm *SnapshotManager) AdvanceTimestamp() uint64

AdvanceTimestamp advances the current timestamp and returns the new value. This is typically called when a transaction commits.

func (*SnapshotManager) CleanupReleasedSnapshots 

func (sm *SnapshotManager) CleanupReleasedSnapshots() int

CleanupReleasedSnapshots removes all released snapshots from the map. Returns the number of snapshots removed.

func (*SnapshotManager) CreateSnapshot 

func (sm *SnapshotManager) CreateSnapshot(txn *tx.Transaction) (*Snapshot, error)

CreateSnapshot creates a new snapshot for the given transaction. The snapshot captures the current timestamp and the list of active transactions.

func (*SnapshotManager) CurrentTimestamp 

func (sm *SnapshotManager) CurrentTimestamp() uint64

CurrentTimestamp returns the current logical timestamp.

func (*SnapshotManager) GetAllActiveSnapshots 

func (sm *SnapshotManager) GetAllActiveSnapshots() []*Snapshot

GetAllActiveSnapshots returns a list of all active (non-released) snapshots.

func (*SnapshotManager) GetOldestActiveSnapshot 

func (sm *SnapshotManager) GetOldestActiveSnapshot() uint64

GetOldestActiveSnapshot returns the timestamp of the oldest active snapshot. This is used to determine which old versions can be garbage collected. Returns 0 if there are no active snapshots.

func (*SnapshotManager) GetSnapshot 

func (sm *SnapshotManager) GetSnapshot(timestamp uint64) *Snapshot

GetSnapshot returns the snapshot with the given timestamp.

func (*SnapshotManager) ReleaseSnapshot 

func (sm *SnapshotManager) ReleaseSnapshot(snapshot *Snapshot) error

ReleaseSnapshot releases a snapshot, allowing garbage collection of old versions that are no longer visible to any active snapshot.

func (*SnapshotManager) SetTimestamp 

func (sm *SnapshotManager) SetTimestamp(ts uint64)

SetTimestamp sets the current timestamp (used for recovery).

func (*SnapshotManager) Stats 

func (sm *SnapshotManager) Stats() SnapshotManagerStats

Stats returns current statistics about the snapshot manager.

type SnapshotManagerStats 

type SnapshotManagerStats struct {
	CurrentTimestamp      uint64
	TotalSnapshots        int
	ActiveSnapshots       int
	ReleasedSnapshots     int
	OldestActiveTimestamp uint64
}

Stats returns statistics about the snapshot manager.

type TrackedVisibilityChecker 

type TrackedVisibilityChecker struct {
	*VisibilityChecker
	// contains filtered or unexported fields
}

TrackedVisibilityChecker wraps VisibilityChecker with statistics tracking.

func NewTrackedVisibilityChecker 

func NewTrackedVisibilityChecker(sm *SnapshotManager) *TrackedVisibilityChecker

NewTrackedVisibilityChecker creates a new TrackedVisibilityChecker.

func (*TrackedVisibilityChecker) GetStats 

func (tvc *TrackedVisibilityChecker) GetStats() VisibilityStats

GetStats returns the current visibility statistics.

func (*TrackedVisibilityChecker) IsVisible 

func (tvc *TrackedVisibilityChecker) IsVisible(version *Version, snapshot *Snapshot) bool

IsVisible checks visibility and tracks statistics.

func (*TrackedVisibilityChecker) ResetStats 

func (tvc *TrackedVisibilityChecker) ResetStats()

ResetStats resets the visibility statistics.

type Version 

type Version struct {
	// TxID is the transaction ID that created this version.
	TxID uint64

	// CommitTS is the commit timestamp (0 if uncommitted).
	// A version is visible to a snapshot if CommitTS <= snapshot and CommitTS > 0.
	CommitTS uint64

	// Data contains the entry data for this version.
	// For deleted entries, this may be nil or empty.
	Data []byte

	// Prev points to the previous version in the chain.
	// nil indicates this is the oldest version.
	Prev *Version

	// PageID is the storage location page ID.
	PageID storage.PageID

	// SlotID is the slot index within the page.
	SlotID uint16

	// State indicates whether this version is active or deleted.
	State VersionState
	// contains filtered or unexported fields
}

Version represents a single version of an entry in the version chain. Each modification creates a new version linked to the previous one. Readers traverse the chain to find the version visible to their snapshot.

func DeserializeVersionHeader 

func DeserializeVersionHeader(buf []byte) (*Version, error)

DeserializeHeader deserializes a version header from bytes.

func FindVisibleVersionInChain 

func FindVisibleVersionInChain(head *Version, snapshot *Snapshot) *Version

FindVisibleVersionInChain is a standalone function that finds the visible version in a version chain. This can be used without a VisibilityChecker instance.

func NewCommittedVersion 

func NewCommittedVersion(data []byte, pageID storage.PageID, slotID uint16) *Version

NewCommittedVersion creates a version that is already committed (loaded from disk).

func NewDeletedVersion 

func NewDeletedVersion(txID uint64, pageID storage.PageID, slotID uint16) *Version

NewDeletedVersion creates a new version that marks an entry as deleted.

func NewVersion 

func NewVersion(txID uint64, data []byte, pageID storage.PageID, slotID uint16) *Version

NewVersion creates a new version with the given transaction ID and data.

func (*Version) ChainLength 

func (v *Version) ChainLength() int

ChainLength returns the length of the version chain starting from this version.

func (*Version) Clone 

func (v *Version) Clone() *Version

Clone creates a deep copy of the version (without the Prev pointer).

func (*Version) Commit 

func (v *Version) Commit(commitTS uint64)

Commit marks this version as committed with the given timestamp.

func (*Version) GetCommitTS 

func (v *Version) GetCommitTS() uint64

GetCommitTS returns the commit timestamp.

func (*Version) GetData 

func (v *Version) GetData() []byte

GetData returns a copy of the version data.

func (*Version) GetLocation 

func (v *Version) GetLocation() (storage.PageID, uint16)

GetLocation returns the storage location (PageID, SlotID).

func (*Version) GetPrev 

func (v *Version) GetPrev() *Version

GetPrev returns the previous version in the chain.

func (*Version) GetState 

func (v *Version) GetState() VersionState

GetState returns the version state.

func (*Version) GetTxID 

func (v *Version) GetTxID() uint64

GetTxID returns the transaction ID that created this version.

func (*Version) IsActive 

func (v *Version) IsActive() bool

IsActive returns true if this version is active (not deleted).

func (*Version) IsCommitted 

func (v *Version) IsCommitted() bool

IsCommitted returns true if this version has been committed.

func (*Version) IsDeleted 

func (v *Version) IsDeleted() bool

IsDeleted returns true if this version represents a deletion.

func (*Version) IsVisibleTo 

func (v *Version) IsVisibleTo(snapshot uint64, activeTxID uint64) bool

IsVisibleTo determines if this version is visible to the given snapshot. Visibility rules: 1. If the version is uncommitted (CommitTS == 0):

  • Visible only to the transaction that created it (txID == snapshot)

2. If the version is committed (CommitTS > 0):

  • Visible if CommitTS <= snapshot

    3. Deleted versions are visible (to indicate the entry was deleted) but GetVisible will return an error for deleted entries.

func (*Version) SerializeHeader 

func (v *Version) SerializeHeader() []byte

Serialize serializes the version header to bytes.

func (*Version) SetPrev 

func (v *Version) SetPrev(prev *Version)

SetPrev sets the previous version in the chain.

type VersionState 

type VersionState uint8

VersionState represents the state of a version. 

const (
	// VersionActive indicates the version is active and visible.
	VersionActive VersionState = iota
	// VersionDeleted indicates the version has been marked as deleted.
	VersionDeleted
)

func (VersionState) String 

func (s VersionState) String() string

String returns the string representation of a VersionState.

type VersionStore 

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

VersionStore manages version chains for all entries. It provides methods to create, read, and delete versions with proper visibility rules based on transaction snapshots.

func NewVersionStore 

func NewVersionStore(pm *storage.PageManager) *VersionStore

NewVersionStore creates a new VersionStore with the given PageManager.

func NewVersionStoreWithCache 

func NewVersionStoreWithCache(pm *storage.PageManager, cacheSize int) *VersionStore

NewVersionStoreWithCache creates a new VersionStore with a specified cache size.

func (*VersionStore) CacheEntryCount 

func (vs *VersionStore) CacheEntryCount() int

CacheEntryCount returns the number of entries that would be cached.

func (*VersionStore) Clear 

func (vs *VersionStore) Clear()

Clear removes all versions from the store. This is useful for testing.

func (*VersionStore) CommitVersion 

func (vs *VersionStore) CommitVersion(txn *tx.Transaction, commitTS uint64)

CommitVersion commits all versions created by the given transaction. This sets the CommitTS on all uncommitted versions created by the transaction.

func (*VersionStore) CreateVersion 

func (vs *VersionStore) CreateVersion(txn *tx.Transaction, dn string, data []byte) error

CreateVersion creates a new version for the given DN. The new version is linked to the previous version (if any) and becomes the latest version in the chain.

The version is initially uncommitted (CommitTS == 0) and will be committed when the transaction commits.

func (*VersionStore) CreateVersionWithLocation 

func (vs *VersionStore) CreateVersionWithLocation(txn *tx.Transaction, dn string, data []byte) (storage.PageID, uint16, error)

CreateVersionWithLocation creates a new version and returns its storage location.

func (*VersionStore) DeleteVersion 

func (vs *VersionStore) DeleteVersion(txn *tx.Transaction, dn string) error

DeleteVersion marks the entry as deleted by creating a delete version. The delete version is linked to the previous version chain.

func (*VersionStore) EntryCount 

func (vs *VersionStore) EntryCount() int

EntryCount returns the number of entries in the version store.

func (*VersionStore) GarbageCollect 

func (vs *VersionStore) GarbageCollect(oldestActiveSnapshot uint64) int

GarbageCollect removes old versions that are no longer visible to any active snapshot. The oldestActiveSnapshot parameter is the oldest snapshot timestamp that is still active. Versions with CommitTS < oldestActiveSnapshot and that have newer committed versions can be safely removed.

func (*VersionStore) GetLatestVersion 

func (vs *VersionStore) GetLatestVersion(dn string) *Version

GetLatestVersion returns the latest version for a DN (regardless of visibility). This is useful for debugging and testing.

func (*VersionStore) GetVersionChain 

func (vs *VersionStore) GetVersionChain(dn string) []*Version

GetVersionChain returns all versions in the chain for a DN. This is useful for debugging and testing.

func (*VersionStore) GetVisible 

func (vs *VersionStore) GetVisible(dn string, snapshot uint64) (*Version, error)

GetVisible returns the version of the entry visible to the given snapshot. It traverses the version chain to find the appropriate version.

Visibility rules: 1. Start from the latest version 2. For each version in the chain:

  • If uncommitted (CommitTS == 0): visible only to the creating transaction
  • If committed (CommitTS > 0): visible if CommitTS <= snapshot

3. Return the first visible version found 4. If the visible version is deleted, return ErrVersionDeleted 5. If no visible version exists, return ErrNoVisibleVersion

func (*VersionStore) GetVisibleForTx 

func (vs *VersionStore) GetVisibleForTx(dn string, snapshot uint64, activeTxID uint64) (*Version, error)

GetVisibleForTx returns the version visible to a specific transaction. The activeTxID parameter allows uncommitted versions to be visible to their creating transaction.

func (*VersionStore) HasEntry 

func (vs *VersionStore) HasEntry(dn string) bool

HasEntry returns true if an entry exists for the given DN.

func (*VersionStore) LoadCache 

func (vs *VersionStore) LoadCache(path string, expectedTxID uint64) error

LoadCache loads the version store cache from disk. Returns nil if cache was loaded successfully, or an error if cache is missing/stale/corrupt.

func (*VersionStore) LoadCommittedVersion 

func (vs *VersionStore) LoadCommittedVersion(dn string, data []byte, pageID storage.PageID, slotID uint16)

LoadCommittedVersion loads a committed version from disk into the version store. This is used during database initialization to restore persisted data.

func (*VersionStore) RollbackVersion 

func (vs *VersionStore) RollbackVersion(txn *tx.Transaction)

RollbackVersion removes all uncommitted versions created by the given transaction. This restores the version chain to its state before the transaction started.

func (*VersionStore) SaveCache 

func (vs *VersionStore) SaveCache(path string, txID uint64) error

SaveCache persists the version store cache to disk. This allows fast startup by avoiding disk I/O for cached entries.

func (*VersionStore) SetDiskLoader 

func (vs *VersionStore) SetDiskLoader(loader func(dn string) (*Version, storage.PageID, uint16, error))

SetDiskLoader sets the callback function for loading entries from disk.

func (*VersionStore) Stats 

func (vs *VersionStore) Stats() VersionStoreStats

Stats returns current statistics about the version store.

type VersionStoreStats 

type VersionStoreStats struct {
	EntryCount       int
	TotalVersions    int
	ActiveWriters    int
	AverageChainLen  float64
	MaxChainLen      int
	DeletedEntries   int
	UncommittedCount int
}

Stats returns statistics about the version store.

type VisibilityChecker 

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

VisibilityChecker provides methods to determine version visibility based on snapshot isolation rules.

func NewVisibilityChecker 

func NewVisibilityChecker(sm *SnapshotManager) *VisibilityChecker

NewVisibilityChecker creates a new VisibilityChecker with the given SnapshotManager.

func (*VisibilityChecker) CanSeeVersion 

func (vc *VisibilityChecker) CanSeeVersion(version *Version, snapshot *Snapshot) bool

CanSeeVersion is a convenience method that checks if a specific version is visible to a snapshot.

func (*VisibilityChecker) FindVisibleVersion 

func (vc *VisibilityChecker) FindVisibleVersion(head *Version, snapshot *Snapshot) *Version

FindVisibleVersion traverses a version chain and returns the first visible version. Returns nil if no visible version is found.

func (*VisibilityChecker) GetVisibleData 

func (vc *VisibilityChecker) GetVisibleData(head *Version, snapshot *Snapshot) ([]byte, error)

GetVisibleData returns the data from the visible version in the chain. Returns nil if no visible version is found or if the visible version is deleted.

func (*VisibilityChecker) IsVisible 

func (vc *VisibilityChecker) IsVisible(version *Version, snapshot *Snapshot) bool

IsVisible determines if a version is visible to the given snapshot. This implements the core snapshot isolation visibility rules:

1. Uncommitted version from another transaction: NOT visible

  • If CommitTS == 0 and TxID != snapshot.TxID, the version is not visible

2. Committed after snapshot: NOT visible

  • If CommitTS > snapshot.Timestamp, the version is not visible

3. Committed by transaction that was active at snapshot time: NOT visible

  • If the version's TxID is in snapshot.ActiveTxIDs, the version is not visible
  • This prevents seeing changes from transactions that started before the snapshot but committed after

4. Otherwise: VISIBLE

  • The version was committed before the snapshot was taken and by a transaction that was not active at snapshot time

type VisibilityResult 

type VisibilityResult struct {
	// Visible indicates whether the version is visible.
	Visible bool

	// Reason provides a human-readable explanation for the visibility decision.
	Reason string

	// Version is the version that was checked (may be nil).
	Version *Version
}

VisibilityResult contains the result of a visibility check with additional context.

func CheckVisibilityWithReason 

func CheckVisibilityWithReason(version *Version, snapshot *Snapshot) VisibilityResult

CheckVisibilityWithReason performs a visibility check and returns detailed results. This is useful for debugging and understanding visibility decisions.

type VisibilityStats 

type VisibilityStats struct {
	TotalChecks          uint64
	VisibleCount         uint64
	InvisibleUncommitted uint64
	InvisibleFuture      uint64
	InvisibleActiveTx    uint64
}

VisibilityStats tracks visibility check statistics for monitoring.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.