admincache

Documentation

Overview

Package admincache persists administrative geocoding results and warms them from indexed observations.

Index

• type AcquireFunc
• type Entry
• type RetainedVersionsFunc
• type Session
  • func NewSession(store *Store, upstream admingeo.Resolver) (*Session, error)
  • func (s *Session) Close() error
  • func (s *Session) Resolve(ctx context.Context, coordinate admingeo.Coordinate) (admingeo.AdminPath, error)
  • func (s *Session) Version() admingeo.DatasetVersion
• type Store
  • func Open(path string) (*Store, error)
  • func (s *Store) Close() error
  • func (s *Store) Lookup(ctx context.Context, version admingeo.DatasetVersion, ...) (admingeo.AdminPath, bool, error)
  • func (s *Store) MarkWarmComplete(ctx context.Context, version admingeo.DatasetVersion, ...) error
  • func (s *Store) PruneVersions(ctx context.Context, keep ...admingeo.DatasetVersion) error
  • func (s *Store) Put(ctx context.Context, version admingeo.DatasetVersion, entries []Entry) error
  • func (s *Store) WarmComplete(ctx context.Context, version admingeo.DatasetVersion, ...) (bool, error)
• type Warmer
  • func NewWarmer(repository *observations.Repository, store *Store, acquire AcquireFunc, ...) (*Warmer, error)
  • func (w *Warmer) BeginForeground() func()
  • func (w *Warmer) Close() error
  • func (w *Warmer) Trigger()

Types

type AcquireFunc

type AcquireFunc func() (admingeo.Resolver, error)

AcquireFunc acquires a resolver lease. Its Close method must release the lease. A nil resolver and nil error means no generation is currently active.

type Entry

type Entry struct {
	Coordinate admingeo.Coordinate
	Path       admingeo.AdminPath
}

Entry is one successfully resolved coordinate. An empty Path is a negative result and is persisted like any other successful resolution.

type RetainedVersionsFunc

type RetainedVersionsFunc func() []admingeo.DatasetVersion

RetainedVersionsFunc returns dataset versions that remain eligible for use, including the active version and any rollback generation.

type Session

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

Session decorates one resolver lease with persistent cache lookups, a bounded duplicate-coordinate memo, and batched write-through updates. Close flushes cache writes but never closes the upstream resolver.

func NewSession

func NewSession(store *Store, upstream admingeo.Resolver) (*Session, error)

NewSession creates a cache-backed view of upstream.

func (*Session) Close

func (s *Session) Close() error

Close flushes pending cache updates. It does not close the upstream resolver.

func (*Session) Resolve

func (s *Session) Resolve(ctx context.Context, coordinate admingeo.Coordinate) (admingeo.AdminPath, error)

Resolve checks the in-memory and persistent caches before consulting the upstream resolver. Cache failures fall through and do not fail resolution.

func (*Session) Version

func (s *Session) Version() admingeo.DatasetVersion

Version returns the immutable upstream dataset version captured at creation.

type Store

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

Store is a concurrency-safe private SQLite resolution cache.

func Open

func Open(path string) (*Store, error)

Open opens or creates a cache database at path.

func (*Store) Close

func (s *Store) Close() error

Close closes the cache. It is idempotent.

func (*Store) Lookup

func (s *Store) Lookup(ctx context.Context, version admingeo.DatasetVersion, coordinate admingeo.Coordinate) (admingeo.AdminPath, bool, error)

Lookup returns the cached result for an exact coordinate and dataset.

func (*Store) MarkWarmComplete

func (s *Store) MarkWarmComplete(ctx context.Context, version admingeo.DatasetVersion, observationRevision string) error

MarkWarmComplete records a fully successful warm scan.

func (*Store) PruneVersions

func (s *Store) PruneVersions(ctx context.Context, keep ...admingeo.DatasetVersion) error

PruneVersions removes cached data for datasets that can no longer be active or rolled back to. An empty keep list clears the cache.

func (*Store) Put

func (s *Store) Put(ctx context.Context, version admingeo.DatasetVersion, entries []Entry) error

Put atomically stores a batch of successful resolutions for one dataset.

func (*Store) WarmComplete

func (s *Store) WarmComplete(ctx context.Context, version admingeo.DatasetVersion, observationRevision string) (bool, error)

WarmComplete reports whether every resolvable coordinate in an observation revision has been processed for a dataset version.

type Warmer

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

Warmer fills a Store from distinct timeline observation coordinates. It owns one worker goroutine and coalesces concurrent notifications.

func NewWarmer

func NewWarmer(repository *observations.Repository, store *Store, acquire AcquireFunc, retained RetainedVersionsFunc, onError func(error)) (*Warmer, error)

NewWarmer starts an idle warmer. Call Trigger after observation or dataset changes. onError may be nil.

func (*Warmer) BeginForeground

func (w *Warmer) BeginForeground() func()

BeginForeground preempts an active warm pass so it releases its snapshot and resolver lease. Warming restarts after the foreground work finishes. The returned release function is idempotent and should be deferred by timelines.

func (*Warmer) Close

func (w *Warmer) Close() error

Close cancels the active pass and joins the worker. It is idempotent.

func (*Warmer) Trigger

func (w *Warmer) Trigger()

Trigger requests a warm pass. Multiple requests pending at once coalesce. Calls after Close are safe no-ops.