overwrite

Documentation

Overview

Package overwrite provides an ArcTable implementation with overwrite semantics. This ArcTable stores arc sets for single-root graphs with namespace-based isolation.

Bloom Filter: Uses BloomCache component for fast negative lookups.

Concurrency Control: This implementation uses mutex for bloom filter synchronization. For production deployments, consider using a distributed KVStore backend (e.g., TiKV, CockroachDB) that provides transactional guarantees.

Index

• type ArcTable
  • func NewArcTable(opts ...Option) (*ArcTable, error)
  • func NewArcTableWithBloomCache(kv kvstore.KVStore, bloomCache *bloom.BloomCache) (*ArcTable, error)
  • func (e *ArcTable) BatchGet(ctx context.Context, namespace string, root cid.Cid, paths []arcset.Path) (map[arcset.Path]cid.Cid, error)
  • func (e *ArcTable) Close() error
  • func (e *ArcTable) CreateNamespace(ctx context.Context, namespace string, cfg *bloom.NamespaceConfig) error
  • func (e *ArcTable) Get(ctx context.Context, namespace string, root cid.Cid, path arcset.Path) (cid.Cid, error)
  • func (e *ArcTable) Iterate(ctx context.Context, namespace string, root cid.Cid) arcset.Iterator
  • func (e *ArcTable) MightContain(ctx context.Context, namespace string, path arcset.Path) bool
  • func (e *ArcTable) MightContainBatch(ctx context.Context, namespace string, paths []arcset.Path) map[arcset.Path]bool
  • func (e *ArcTable) Snapshot(ctx context.Context, namespace string, root cid.Cid) (arcset.ArcSet, error)
  • func (e *ArcTable) Stats() map[string]any
  • func (e *ArcTable) Update(ctx context.Context, namespace string, newRoot, oldRoot cid.Cid, ...) error
• type Option
  • func WithBloomCache(bloomCache *bloom.BloomCache) Option
  • func WithKVStore(kv kvstore.KVStore) Option

Types

type ArcTable

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

ArcTable is an ArcTable with overwrite semantics. It uses namespace for namespace isolation, allowing multiple graphs to share the same KVStore instance.

func NewArcTable

func NewArcTable(opts ...Option) (*ArcTable, error)

NewArcTable creates a new ArcTable with the given KVStore and optional configuration. Bloom filter is disabled by default; use WithBloomCache to enable it.

Example usage:

// Simple: use defaults
arctable, _ := overwrite.NewArcTable(overwrite.WithKVStore(kv))

// With bloom cache
arctable, _ := overwrite.NewArcTable(
    overwrite.WithKVStore(kv),
    overwrite.WithBloomCache(bloomCache),
)

func NewArcTableWithBloomCache

func NewArcTableWithBloomCache(kv kvstore.KVStore, bloomCache *bloom.BloomCache) (*ArcTable, error)

NewArcTableWithBloomCache creates a new ArcTable with BloomCache for fast negative lookups. Deprecated: Use NewArcTable with WithBloomCache option instead.

func (*ArcTable) BatchGet

func (e *ArcTable) BatchGet(ctx context.Context, namespace string, root cid.Cid, paths []arcset.Path) (map[arcset.Path]cid.Cid, error)

BatchGet retrieves multiple target CIDs in a single operation. Uses bloom filter to filter out definitely-not-present paths.

func (*ArcTable) Close

func (e *ArcTable) Close() error

Close releases resources.

func (*ArcTable) CreateNamespace

func (e *ArcTable) CreateNamespace(ctx context.Context, namespace string, cfg *bloom.NamespaceConfig) error

CreateNamespace creates a new namespace with custom bloom configuration.

func (*ArcTable) Get

func (e *ArcTable) Get(ctx context.Context, namespace string, root cid.Cid, path arcset.Path) (cid.Cid, error)

Get retrieves the target CID for a path within a namespace. First checks bloom filter, then queries KVStore.

func (*ArcTable) Iterate

func (e *ArcTable) Iterate(ctx context.Context, namespace string, root cid.Cid) arcset.Iterator

Iterate returns a streaming iterator over all arcs in the namespace.

func (*ArcTable) MightContain

func (e *ArcTable) MightContain(ctx context.Context, namespace string, path arcset.Path) bool

MightContain checks if a path might exist in the namespace using bloom filter. Returns false if the path definitely doesn't exist (can skip KVStore lookup). Returns true if the path might exist (need to call Get to verify).

func (*ArcTable) MightContainBatch

func (e *ArcTable) MightContainBatch(ctx context.Context, namespace string, paths []arcset.Path) map[arcset.Path]bool

MightContainBatch checks multiple paths at once using bloom filter.

func (*ArcTable) Snapshot

func (e *ArcTable) Snapshot(ctx context.Context, namespace string, root cid.Cid) (arcset.ArcSet, error)

Snapshot returns an immutable snapshot of all arcs in the namespace.

func (*ArcTable) Stats

func (e *ArcTable) Stats() map[string]any

Stats returns bloom filter cache statistics.

func (*ArcTable) Update

func (e *ArcTable) Update(ctx context.Context, namespace string, newRoot, oldRoot cid.Cid, arcs arcset.ArcSet) error

Update stores arc entries with a new commitment root. Updates the namespace bloom filter incrementally.

type Option

type Option func(*options)

Option configures an ArcTable instance.

func WithBloomCache

func WithBloomCache(bloomCache *bloom.BloomCache) Option

WithBloomCache enables the BloomCache for fast negative lookups.

func WithKVStore

func WithKVStore(kv kvstore.KVStore) Option

WithKVStore sets the KVStore backend for the ArcTable.