gopgext/shmem
import "gopgext/shmem"
Package shmem shares state between the backends of a server: shared memory and locks, for libraries loaded by shared_preload_libraries (statistics like pg_stat_statements, caches, counters…).
Objects are created while the library loads (in main or package-level variables), with names unique in the server:
var (
lock = shmem.NewLock("myext")
stats = shmem.NewTable[Key, Counters]("myext stats", 1000)
total = shmem.NewVar[Totals]("myext totals")
)
func record(k Key, d float64) {
lock.Lock()
defer lock.Unlock()
if c, _ := stats.Insert(k); c != nil {
c.Calls++
c.Time += d
}
}
Shared memory isn’t the Go heap: the types of shared values (table keys and values, variables) can’t contain pointers, strings, slices, maps or interfaces, only numbers, booleans and arrays or structs of them (a string can be kept as a fixed-size byte array, or in a Bytes area). The package checks this when objects are created. Values returned point into shared memory: other backends see changes, so access them only while holding a lock that protects them (shared for reading, exclusive for writing); tables and areas have no lock of their own.
If the library isn’t loaded by shared_preload_libraries, objects can be created but not used: Available reports false, and using them raises an error saying the library must be preloaded.
Index#
func Available() boolfunc OnShutdown(f func())func OnStartup(f func())- type Bytes
- type Lock
- type SpinLock
- type Table
func NewTable[K comparable, V any](name string, size int) *Table[K, V]func (t *Table[K, V]) All() iter.Seq2[K, *V]func (t *Table[K, V]) Cap() intfunc (t *Table[K, V]) Delete(k K) boolfunc (t *Table[K, V]) Get(k K) *Vfunc (t *Table[K, V]) Insert(k K) (v *V, inserted bool)func (t *Table[K, V]) Len() int
- type Var
Functions#
func Available#
func Available() bool
Available reports whether the library was loaded by shared_preload_libraries, so its shared memory exists.
func OnShutdown#
func OnShutdown(f func())
OnShutdown registers a function the postmaster runs when the server shuts down cleanly (not after a crash), after the backends have exited, e.g. to save state to a file (pg.WriteFile). Errors are logged.
func OnStartup#
func OnStartup(f func())
OnStartup registers a function the postmaster runs when it creates the shared memory (at server start, and again after a crash of a backend resets it), e.g. to load state saved by OnShutdown. Objects are usable; it runs without transaction or locks, and its errors are logged.
Types#
type Bytes#
type Bytes struct {
// contains filtered or unexported fields
}
Bytes is a fixed-size area of shared memory, zero initially: for variable-size data (strings…) the extension lays out itself.
func NewBytes#
func NewBytes(name string, size int) *Bytes
NewBytes creates an area of size bytes (aligned to 8 bytes).
func (*Bytes) Slice#
func (b *Bytes) Slice() []byte
Slice returns the area.
type Lock#
type Lock struct {
// contains filtered or unexported fields
}
Lock is a lightweight lock (LWLock) shared by all backends. Its name is the wait event backends show while waiting for it (pg_stat_activity). Locks are released automatically if the transaction fails, but hold them briefly: interrupts (query cancel) wait until they are released.
func NewLock#
func NewLock(name string) *Lock
NewLock creates a lock.
func (*Lock) Lock#
func (l *Lock) Lock()
Lock acquires the lock exclusively (to write), waiting if needed.
func (*Lock) RLock#
func (l *Lock) RLock()
RLock acquires the lock shared (to read), waiting if needed.
func (*Lock) Unlock#
func (l *Lock) Unlock()
Unlock releases the lock.
type SpinLock#
type SpinLock struct {
// contains filtered or unexported fields
}
SpinLock is a spinlock to embed in shared values: it protects a few fields for a few instructions (e.g. counters updated while holding a Lock shared), never while calling PostgreSQL or allocating. The zero value is unlocked.
func (*SpinLock) Lock#
func (s *SpinLock) Lock()
Lock acquires the spinlock, spinning (then sleeping briefly) while another backend holds it.
func (*SpinLock) Unlock#
func (s *SpinLock) Unlock()
Unlock releases the spinlock.
type Table#
type Table[K comparable, V any] struct {
// contains filtered or unexported fields
}
Table is a hash table in shared memory (a dynahash table) with at most a fixed number of entries, from keys K to values V. Keys are compared and hashed as bytes: K can’t have padding between or after its fields (add explicit “_ [n]byte” fields), and floating-point keys compare by representation.
func NewTable#
func NewTable[K comparable, V any](name string, size int) *Table[K, V]
NewTable creates a table of up to size entries.
func (*Table[K, V]) All#
func (t *Table[K, V]) All() iter.Seq2[K, *V]
All returns the entries, in no particular order: those in the table when called, which can be modified (not deleted) while iterating.
func (*Table[K, V]) Cap#
func (t *Table[K, V]) Cap() int
Cap returns the maximum number of entries.
func (*Table[K, V]) Delete#
func (t *Table[K, V]) Delete(k K) bool
Delete removes k, reporting whether it was in the table.
func (*Table[K, V]) Get#
func (t *Table[K, V]) Get(k K) *V
Get returns the value of k, or nil.
func (*Table[K, V]) Insert#
func (t *Table[K, V]) Insert(k K) (v *V, inserted bool)
Insert returns the value of k, adding a zero value if k wasn’t in the table (inserted). It returns nil if the table is full.
func (*Table[K, V]) Len#
func (t *Table[K, V]) Len() int
Len returns the number of entries.
type Var#
type Var[T any] struct {
// contains filtered or unexported fields
}
Var is a value of type T in shared memory, zero initially.
func NewVar#
func NewVar[T any](name string) *Var[T]
NewVar creates a shared variable.
func (*Var[T]) Ptr#
func (v *Var[T]) Ptr() *T
Ptr returns the variable.