cache

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrBufferFull = errors.New("timeline manager: pending save limit exceeded")
View Source
var ErrClosed = errors.New("timeline manager: shut down")

Functions

This section is empty.

Types

type Cache

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

Cache owns the policy joining ttlcache and Store. Writes acknowledge memory acceptance; Flush is the optional persistence checkpoint. This is a best-effort cache, without durable delivery or cross-process consistency. spec: Eviction schedules one final bounded save. Failure is reported and the buffer is released, so an unavailable Store cannot pin memory indefinitely.

func New

func New(backend store.Store, config Config) (*Cache, error)

New starts a background saving cache.

func NewStandalone

func NewStandalone(backend store.Store) (*Cache, error)

NewStandalone shares the same cache/Store protocol without a background worker. Its owner explicitly flushes one ID and retains it for the recorder lifetime.

func (*Cache) Closed

func (c *Cache) Closed() bool

Closed reports whether new writes and loads are rejected.

func (*Cache) Evict

func (c *Cache) Evict(id string)

Evict releases a cached copy and schedules its final best-effort save. Later access loads persistent state; an unsaved last update may be absent from it.

func (*Cache) Flush

func (c *Cache) Flush(ctx context.Context, id string, wait bool) error

Flush triggers the save worker. Waiting captures only records accepted before this call; caller cancellation never cancels the shared Store submission.

func (*Cache) Read

func (c *Cache) Read(ctx context.Context, id string, fresh bool) (model.Snapshot, error)

Read optionally refreshes the Store view. Local unsubmitted updates are always overlaid; a fresh read never implicitly flushes and cannot see unsubmitted peers.

func (*Cache) Shutdown

func (c *Cache) Shutdown(ctx context.Context) error

Shutdown stops both workers, then attempts a caller-scoped final drain. Store connections remain owned by the application. Failed buffers are released.

func (*Cache) Stats

func (c *Cache) Stats() Stats

func (*Cache) Update

func (c *Cache) Update(ctx context.Context, id string, fn func(store.Document) (store.Update, error)) error

update builds one update against the current local document, atomically with other updates to this cache entry. The callback gets a detached document and must not reenter this Cache or perform IO. This is not a distributed transaction.

func (*Cache) Write

func (c *Cache) Write(ctx context.Context, id string, update store.Update) error

Write accepts facts into memory and schedules persistence. It may read Store on a cache miss; success does not mean the facts have reached persistent storage.

type Config

type Config struct {
	Actor               model.Actor   // optional default recording actor, overridden by stage options
	BatchLimit          int           // default 64 IDs per save batch, MGet or Latest
	LoadInterval        time.Duration // default 1s between background loads
	MaxTimelines        int           // default 1024 cached documents
	FlushInterval       time.Duration // default 1s between background saves
	ExportTimeout       time.Duration // default 5s for each Store read/merge
	MaxPendingTimelines int           // default 1024, including evicted documents awaiting a final save
	MaxPendingUpdates   int           // default 1024 per document, before coalescing a save batch
	// OnError reports synchronization failures outside locks; batch load errors
	// use an empty ID. Both workers may call concurrently. It must return promptly and
	// must not call Shutdown. Default: slog with the timeline ID, without data.
	OnError func(id string, err error)
}

Config bounds cache capacity and backend calls. Zero fields select defaults.

type Stats

type Stats struct {
	CachedTimelines  int
	PendingTimelines int
	PendingUpdates   int
	DroppedUpdates   uint64
	RejectedUpdates  uint64
}

Jump to

Keyboard shortcuts

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