Documentation
¶
Overview ¶
Package cache defines a generic read-result cache with per-relation invalidation. A write invalidates the relation it changed (and the database's derived entries, such as views) precisely, rather than relying on blind TTL expiry (Oracle result-cache semantics). Entries are keyed by the physical relation, not the entity, so every path to a table sees its writes.
Index ¶
- type Cache
- type InvalidateOnly
- type Key
- type NoopCache
- type Sized
- type TTLCache
- func (c *TTLCache[T]) DropGeneration(generation uint64)
- func (c *TTLCache[T]) Get(ctx context.Context, k Key) (T, bool)
- func (c *TTLCache[T]) GetSized(_ context.Context, k Key) (T, int64, bool)
- func (c *TTLCache[T]) Invalidate(database, relation string) error
- func (c *TTLCache[T]) Set(ctx context.Context, k Key, v T, stamp uint64) error
- func (c *TTLCache[T]) SetSized(_ context.Context, k Key, v T, stamp uint64, size int64) error
- func (c *TTLCache[T]) Stamp(database string) uint64
- func (c *TTLCache[T]) UpdateLimits(ttl time.Duration, maxSize int, maxBytes int64)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache[T any] interface { Get(ctx context.Context, k Key) (T, bool) // Stamp returns how many times database was invalidated. A reader takes // it before querying and passes it to Set, which stores nothing when the // database was invalidated meanwhile: the result may predate the write. Stamp(database string) uint64 Set(ctx context.Context, k Key, v T, stamp uint64) error // Invalidate drops the entries reading relation of database and every // derived entry of database; an empty relation drops all of database. Invalidate(database, relation string) error }
Cache is a generic read cache with per-relation invalidation.
type InvalidateOnly ¶ added in v0.1.12
InvalidateOnly is a Cache that reads and stores nothing but passes invalidations on to Cache: a configuration with caching off still invalidates what the configurations sharing that cache stored.
func (InvalidateOnly[T]) Get ¶ added in v0.1.12
func (InvalidateOnly[T]) Get(_ context.Context, _ Key) (T, bool)
Get always misses.
func (InvalidateOnly[T]) Invalidate ¶ added in v0.1.12
func (c InvalidateOnly[T]) Invalidate(database, relation string) error
Invalidate passes the invalidation on.
func (InvalidateOnly[T]) Stamp ¶ added in v0.1.12
func (c InvalidateOnly[T]) Stamp(database string) uint64
Stamp implements Cache.
type Key ¶
type Key struct {
// Database is the physical database the entry reads: invalidation
// matches it across datasources and configuration generations.
Database string
Relation string
// Datasource and Generation keep lookups apart: datasources may reach
// one database through accounts that see different rows, and a reloaded
// configuration may read it under different rules.
Datasource string
Generation uint64
SQL string
Args string
Scope string
}
Key identifies a cached entry: the relation it reads (Relation of Database; empty for data derived from other relations of the database, such as a view), the statement, and Scope, which separates authorization and row-level identities.
type NoopCache ¶
type NoopCache[T any] struct{}
NoopCache is a Cache that stores nothing.
func (NoopCache[T]) Invalidate ¶
Invalidate is a no-op.
type Sized ¶ added in v0.1.21
type Sized[T any] interface { SetSized(ctx context.Context, k Key, v T, stamp uint64, size int64) error GetSized(ctx context.Context, k Key) (T, int64, bool) }
Sized is a Cache bounding the bytes its entries hold: SetSized is Set of a value of size bytes, and GetSized is Get with the size it was stored with (0 when stored with Set).
type TTLCache ¶
type TTLCache[T any] struct { // contains filtered or unexported fields }
TTLCache stores values with a TTL. Entries are indexed by database, so an invalidation touches only that database's entries, and kept in a heap by expiry, so Set drops the expired entries and, over the caps (entries, and bytes of the entries stored with SetSized), the ones closest to expiry without scanning the others.
func NewTTLCache ¶
NewTTLCache returns a TTLCache. maxSize <= 0 uses a safe default capacity.
func (*TTLCache[T]) DropGeneration ¶ added in v0.1.12
DropGeneration drops the entries a configuration generation stored: once it serves no request, nothing reads them.
func (*TTLCache[T]) Invalidate ¶
Invalidate implements Cache.
func (*TTLCache[T]) Set ¶
Set stores a value with the configured TTL unless k's database was invalidated since stamp, evicting if over maxSize.
func (*TTLCache[T]) SetSized ¶ added in v0.1.21
SetSized implements Sized: a value larger than the byte cap is not stored.