Documentation
¶
Overview ¶
Package index reads a schema-versioned JSON document of per-model measurements into a value every reader in a process can share.
THE INDEX IS READ-ONLY AND IMMUTABLE, which is the whole design: nothing merges into it and nothing mutates it after Parse, so one document may be handed to every goroutine without a lock. Whoever read the file stays outside the package — Parse takes bytes, Read takes a reader, and Fallback chooses between two documents that both arrive as bytes.
FORWARD COMPATIBILITY IS THE POINT. An unknown top-level field, an unknown metric kind, an undeclared dim on a cell and an unknown cell field are all ignored, because a reader that refused them would make every future field a flag day. The one thing refused outright is a schema this reader does not understand, which is what the schema number exists to say.
Index ¶
- Variables
- func Seed() []byte
- type Cell
- type Index
- func (x *Index) Canonical(model string) string
- func (x *Index) Cell(metric, role, model string, dims map[string]string) (Cell, bool)
- func (x *Index) Cells(metric string) []Cell
- func (x *Index) Dims(metric string) []string
- func (x *Index) Generated() time.Time
- func (x *Index) Judges() []string
- func (x *Index) Kind(metric string) (string, bool)
- func (x *Index) Metrics() []string
- func (x *Index) MinInstalls() int
- func (x *Index) Rubrics() map[string]int
- func (x *Index) Schema() int
- func (x *Index) Unit(metric string) string
- func (x *Index) Wanted() []Want
- type Want
Constants ¶
This section is empty.
Variables ¶
var ErrSchema = errors.New("document schema is newer than this reader")
ErrSchema is wrapped by the error a document whose schema is newer than this reader returns. A reader that is behind the document cannot guess what the newer fields mean, so it refuses rather than half-reads.
Functions ¶
Types ¶
type Cell ¶
type Cell struct {
Metric string
Role string
Model string
Mean float64
SD float64
N int
Installs int
Dims map[string]string
}
Cell is one measurement from the document. Dims carries the declared dims beyond role and model that the cell spelled, and is nil for a cell that carried none. Installs is the contributor count the cell spells — the one the floor reads it on; a cell that spells none, the shape the seed carries, reads zero, its rows being the only count the document gives.
type Index ¶
type Index struct {
// contains filtered or unexported fields
}
Index is a parsed measurement document. Nothing on it mutates after it is built, and every accessor hands back copies, so many goroutines may read one Index at once.
func Fallback ¶
Fallback answers with the document that should be trusted: primary, unless it is missing, empty, unparsable, or older by its generated date, in which case the embedded one. Equal dates keep primary. When neither parses it returns the error from the embedded document.
func Read ¶
Read reads a measurement document from a reader. The reader is drained and closed by nobody but the caller; the document is all this package takes.
func SeedIndex ¶
SeedIndex parses the embedded document — the index a machine with no cache starts from. The error is returned rather than panicking, though the seed is a file this build was shipped with and a test in this package parses it, so an error here is a bug and not a mode.
func (*Index) Canonical ¶
Canonical answers with the canonical id the document spells for a model id, for the id itself and for any of its alternates, and with the normalised input for an id the document never names.
func (*Index) Cell ¶
Cell addresses a measurement exactly: metric, role, model and dims all have to match, and a nil dims map and an empty one are the same address. A lookup with no dims finds the cell that carries none, and never a cell that carries some.
func (*Index) Cells ¶
Cells answers with every returnable cell of one metric, sorted by role, then model, then by its dims rendered as sorted "key=value" pairs.
func (*Index) Dims ¶
Dims answers with the metric's declared dims beyond role and model, sorted. Role and model are the address of every cell and are never repeated here. A metric that declares no dim beyond them, and a name the document does not declare, answer empty.
func (*Index) Generated ¶
Generated is the document's "generated" day in UTC. A missing or unreadable date is the zero time, which sorts as the oldest thing there is.
func (*Index) Kind ¶
Kind answers with the kind word the document spells for the metric, lowercased, whether or not this build knows it.
func (*Index) MinInstalls ¶
MinInstalls is the document's floor on the installs behind a measurement, which a cell that carries none meets on its rows.
func (*Index) Schema ¶
Schema is the document's schema version. A missing schema reads as 0 and is accepted.
Source Files
Directories