memory

package

v0.5.3 Latest Latest Go to latest Published: Nov 3, 2026 License: MIT Imports: 14 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/weiloon1234/Foundry-Go

Links

Open Source Insights

Documentation ¶

Overview ¶

Package memory supplies a bounded, concurrency-safe cache backend for local development and deterministic tests. It does not provide distributed guarantees.

Index ¶

type Backend
- func New(config Config, source clock.Clock) (*Backend, error)
type Config
- func DefaultConfig() Config
- func (c Config) Validate() error
type Stats

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type Backend ¶

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

Backend owns immutable serialized snapshots and their expiry/LRU indexes. New performs no I/O and starts no goroutines. Close rejects new operations and releases this backend's memory; typed Store handles borrow this capability. Reads share a read lock and never reorder storage: they mark entries referenced, and expired or unusable entries they meet are reclaimed later by writes, capacity pressure or Stats. Mutations take the exclusive lock.

func New ¶

func New(config Config, source clock.Clock) (*Backend, error)

New validates limits and borrows a clock without starting goroutines.

func (*Backend) Add ¶

func (b *Backend) Add(ctx context.Context, key cache.EntryKey, data []byte, ttl cache.TTL) (bool, error)

Add atomically copies and inserts an absent entry, retaining an existing live value and TTL.

func (*Backend) AddTagged ¶

func (b *Backend) AddTagged(ctx context.Context, key cache.TaggedKey, data []byte, ttl cache.TTL) (bool, error)

AddTagged atomically inserts only when the current snapshot has no live value.

func (*Backend) Close ¶

func (b *Backend) Close(ctx context.Context) error

Close rejects new operations and releases retained entries. Repeated calls are safe.

func (*Backend) Exists ¶

func (b *Backend) Exists(ctx context.Context, key cache.EntryKey) (bool, error)

Exists reports whether a usable live plain entry exists without copying its payload.

func (*Backend) ExistsTagged ¶

func (b *Backend) ExistsTagged(ctx context.Context, key cache.TaggedKey) (bool, error)

ExistsTagged checks a live entry under its tag snapshot, returning fault.Conflict for stale metadata.

func (*Backend) Expire ¶

func (b *Backend) Expire(ctx context.Context, key cache.EntryKey, ttl cache.TTL) (bool, error)

Expire changes a live plain entry's TTL without changing its payload.

func (*Backend) ExpireTagged ¶

func (b *Backend) ExpireTagged(ctx context.Context, key cache.TaggedKey, ttl cache.TTL) (bool, error)

ExpireTagged atomically validates the tag snapshot and changes a live entry's TTL.

func (*Backend) Forget ¶

func (b *Backend) Forget(ctx context.Context, key cache.EntryKey) (bool, error)

Forget removes a live entry and reports whether it existed.

func (*Backend) ForgetMany ¶

func (b *Backend) ForgetMany(ctx context.Context, keys []cache.EntryKey) (uint64, error)

ForgetMany validates and atomically removes a canonical batch, counting live entries.

func (*Backend) ForgetManyTagged ¶

func (b *Backend) ForgetManyTagged(ctx context.Context, keys []cache.TaggedKey) (uint64, error)

ForgetManyTagged removes a canonical batch atomically under one current tag snapshot.

func (*Backend) ForgetTagged ¶

func (b *Backend) ForgetTagged(ctx context.Context, key cache.TaggedKey) (bool, error)

ForgetTagged removes the stored entry under a current snapshot and reports whether its value was current.

func (*Backend) FoundryAdapter ¶

func (*Backend) FoundryAdapter(frameworkadapter.Seal)

FoundryAdapter marks the backend as framework-owned adapter I/O.

func (*Backend) Get ¶

func (b *Backend) Get(ctx context.Context, key cache.EntryKey) ([]byte, bool, error)

Get returns an owned copy of a live entry and lazily reclaims expired storage.

func (*Backend) GetMany ¶

func (b *Backend) GetMany(ctx context.Context, keys []cache.EntryKey) ([]cache.BatchValue, error)

GetMany reads a canonical batch under one shared lock; results follow input order.

func (*Backend) GetManyTagged ¶

func (b *Backend) GetManyTagged(ctx context.Context, keys []cache.TaggedKey) ([]cache.BatchValue, error)

GetManyTagged validates one shared snapshot and reads the batch atomically.

func (*Backend) GetTagged ¶

func (b *Backend) GetTagged(ctx context.Context, key cache.TaggedKey) ([]byte, bool, error)

GetTagged returns owned bytes under a current snapshot and reclaims obsolete entries.

func (*Backend) Increment ¶

func (b *Backend) Increment(ctx context.Context, key cache.EntryKey, delta int64, initialTTL cache.TTL) (int64, error)

Increment changes the same entry used by the other cache operations, under the same mutex. Existing expiry is preserved and failures leave its data unchanged.

func (*Backend) IncrementTagged ¶

func (b *Backend) IncrementTagged(ctx context.Context, key cache.TaggedKey, delta int64, ttl cache.TTL) (int64, error)

IncrementTagged atomically increments the counter under a current tag snapshot, preserving an existing expiry.

func (*Backend) InvalidateTags ¶

func (b *Backend) InvalidateTags(ctx context.Context, keys []cache.EntryKey) error

InvalidateTags atomically replaces the selected metadata with fresh random versions.

func (*Backend) Put ¶

func (b *Backend) Put(ctx context.Context, key cache.EntryKey, data []byte, ttl cache.TTL) error

Put copies and replaces the entry and TTL, evicting entries when capacity requires it.

func (*Backend) PutTagged ¶

func (b *Backend) PutTagged(ctx context.Context, key cache.TaggedKey, data []byte, ttl cache.TTL) error

PutTagged copies and replaces an entry under a current tag snapshot.

func (*Backend) ResolveTags ¶

func (b *Backend) ResolveTags(ctx context.Context, keys []cache.EntryKey) ([]cache.TagVersion, error)

ResolveTags reads existing metadata under the shared lock and takes the exclusive lock only when a version must be created.

func (*Backend) Stats ¶

func (b *Backend) Stats() Stats

Stats reclaims expired entries and returns current capacity and eviction totals.

type Config ¶

type Config struct {
	MaxEntries int
	MaxBytes   int
}

Config bounds both entry count and the sum of physical-key and payload bytes. Map/list overhead is additionally bounded by MaxEntries. Recency eviction (LRU with a second chance for entries read since they were last ordered) applies after expired entries have been reclaimed. An oversized entry is rejected.

func DefaultConfig ¶

func DefaultConfig() Config

DefaultConfig returns limits of 10,000 entries and 64 MiB of key and payload bytes.

func (Config) Validate ¶

func (c Config) Validate() error

Validate returns fault.Invalid unless both capacity limits are positive.

type Stats ¶

type Stats struct {
	Entries   int
	Bytes     int
	Evictions uint64
	Closed    bool
}

Stats reports live entries after lazy expiry collection. Bytes includes keys and payloads; it is not a measurement of total process memory.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL