pcache

Documentation

Overview

Package pcache provides a bounded, LRU-evicting page cache suitable for registration with modernc.org/sqlite via sqlite.RegisterPageCache. It is the reference implementation that accompanies the SQLITE_CONFIG_PCACHE2 wrapper defined in the parent package.

The contract this package implements is documented on sqlite.PageCache, sqlite.Cache, and sqlite.Page. In brief: SQLite calls Pool.Create once per database connection; each returned cache holds at most cache_size pages (the soft cap set by PRAGMA cache_size), evicts the least-recently-unpinned page when it has to make room, and stores page memory off the Go heap so SQLite's interior pointer arithmetic on the page extras does not trip the race detector's checkptr enforcement.

Typical use:

import (
    "modernc.org/sqlite"
    "modernc.org/sqlite/pcache"
)

func init() {
    sqlite.MustRegisterPageCache(pcache.New())
}

Call New once and save the result; two distinct *Pool values compare unequal and would trip sqlite.ErrPageCacheConflict if both were registered.

Cross-connection sharing (one Pool serving multiple databases from a shared page set) is not in scope for this package today; each sqlite.PageCache.Create returns a fresh per-database cache. The hook for that lives at the binding level and is the subject of a separate MR.

Index

• type Pool
  • func New() *Pool
  • func (p *Pool) Create(pageSize, extraSize int, purgeable bool) (sqlite.Cache, error)
  • func (p *Pool) Stats() Stats
• type Stats

Types

type Pool

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

Pool is the factory side of the sqlite.PageCache contract. It is safe for concurrent Pool.Create calls (one per opening connection); each returned sqlite.Cache runs single-goroutine per the parent package's SQLITE_OPEN_FULLMUTEX + database/sql contract.

Pool aggregates summary counters across every cache it has created so a long-running process can observe hit/miss/eviction behaviour through Pool.Stats without instrumenting individual caches.

func New

func New() *Pool

New returns a Pool with empty counters. Multiple New values compare unequal; call once and reuse.

func (*Pool) Create

func (p *Pool) Create(pageSize, extraSize int, purgeable bool) (sqlite.Cache, error)

Create allocates a fresh per-database cache. It is the sqlite.PageCache entry point; SQLite calls it through the binding each time a new database connection's page cache is wired up.

func (*Pool) Stats

func (p *Pool) Stats() Stats

Stats returns a snapshot of the Pool's lifetime counters.

type Stats

type Stats struct {
	Hits   int64 // Fetches that found an existing page
	Misses int64 // Fetches that did not find one
	Allocs int64 // Fresh page allocations from libc

	// Evictions counts every page release through the standard
	// per-page paths: LRU-tail eviction (FetchCreateForce at cap,
	// SetSize shrink-to-target, Shrink, and Unpin(discard=false)
	// trimming back to target after a FetchCreateForce overcommit)
	// and Unpin(discard=true).
	// It does NOT count bulk frees performed by Truncate, Rekey
	// collisions, or Destroy.
	Evictions int64

	// EasyRefusals counts how often a FetchCreateEasy returned nil
	// because the cache was at PRAGMA cache_size and an allocation
	// would require eviction. SQLite handles a refusal by spilling
	// dirty pages and retrying with FetchCreateForce, so this counter
	// is a direct proxy for the I/O pressure the strict Easy contract
	// adds vs pcache1's recycle-without-spill behavior at cap.
	EasyRefusals int64

	Rekeys    int64 // Rekey calls forwarded to the cache
	Truncates int64 // Truncate calls forwarded to the cache
	Caches    int64 // Caches created over the Pool's lifetime
}

Stats is a snapshot of a Pool's lifetime counters. The counters are monotonically non-decreasing across the lifetime of the Pool.