Documentation
¶
Overview ¶
Package alloc is graphdb's allocator seam for out-of-memory testing.
SQLite tests its out-of-memory paths by substituting the allocator through sqlite3_config(SQLITE_CONFIG_MALLOC, ...) and running two loops:
Rig the allocator to fail once on the N-th allocation for N=1,2,3,.... Repeat until no memory allocations fail. Rig the allocator to fail all allocations beginning with the N-th, for N=1,2,3,.... Repeat until no memory allocations fail.
What this can and cannot claim ¶
Go cannot substitute malloc. A Go program that exhausts memory is killed by the runtime or the OOM killer; there is no error to return and no stack to unwind. Any package claiming to test "out of memory" in Go is claiming something narrower, so this one says exactly what it covers:
- Covered: graphdb's own large, length-driven buffers — the ones sized from a record header, a snapshot section, or a query result. Those have real failure paths, because the size comes from data and the data can be wrong or simply too big for a budget.
- Not covered: every implicit allocation Go makes — slice growth, map rehashing, interface boxing, goroutine stacks. Nothing here touches them.
That is a smaller claim than SQLite's, and it is the honest one. The value is the same in kind: an error path that no test can otherwise reach gets executed, and a budget becomes enforceable.
Cost ¶
Bytes is one atomic load and a make when nothing is installed, which is the production case always.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoMemory = fmt.Errorf("alloc: allocation refused")
ErrNoMemory is returned when an installed allocator refuses a request. It is the error a caller must handle; graphdb treats it like any other failure to obtain a resource, not like corruption.
Functions ¶
func Allocs ¶
func Allocs() int
Allocs reports how many requests were made since an allocator was installed.
This is the negative control. A test that installs a failing allocator and sees the expected error has proved nothing unless an allocation was actually attempted — the same error can arrive from elsewhere. Assert Allocs > 0.
func Bytes ¶
Bytes returns a buffer of n bytes.
With no allocator installed it is a plain make, and the error is always nil. Callers must still handle the error: that is the point, because the handler is the code this package exists to execute.
func Install ¶
func Install(a Allocator)
Install replaces the allocator. Passing nil restores the default.
The state is process-wide, exactly as sqlite3_config's is. A test that installs one must defer Reset, or every later test in the same binary inherits it.
Source Files
Directories