Course 10 gave you a tag parser. Course 08 measured what it costs: around 500 nanoseconds and 13 allocations to read one struct’s tags. Every query would pay that.
So you cache it. The package is about sixty lines and it has one hard requirement — every query, on every goroutine, reads from it at once.
This course has a benchmark in the middle that contradicts what course 07 told you. Run it yourself.
The cheapest possible cache
In your greet module:
type Registry struct {
tables map[reflect.Type]*TableMetadata
}
func (r *Registry) Get(t reflect.Type) (*TableMetadata, bool) {
m, ok := r.tables[t]
return m, ok
}
A map from type to metadata. Course 08 already showed the payoff:
BenchmarkParseUncached 507.3 ns/op 488 B/op 13 allocs/op
BenchmarkParseCached 10.4 ns/op 0 B/op 0 allocs/op
Roughly fifty times faster and no garbage. That is the whole reason this package exists, and it is also the entire easy part.
Predict: which lock is faster?
Course 07 said readers must not block each other or the lock becomes a bottleneck. So put the same map behind each kind of lock and race eleven goroutines at it:
func (r *RW) Get(t reflect.Type) *meta { r.mu.RLock(); defer r.mu.RUnlock(); return r.m[t] }
func (r *MU) Get(t reflect.Type) *meta { r.mu.Lock(); defer r.mu.Unlock(); return r.m[t] }
go test -bench=MapLookup -benchmem -run=^$ .
Predict the gap before you run it. Many readers, one map lookup each.
BenchmarkRWMutex_MapLookup-11 98.14 ns/op
BenchmarkMutex_MapLookup-11 100.7 ns/op
Two and a half percent. Not 10×, not 2× — nothing.
The reason is that RLock is not free. It atomically increments a shared reader
counter, and that counter lives on one cache line that every core has to fight
over. A Mutex fights over one word too. When the work inside the lock is a
single map lookup — about ten nanoseconds — the contention on the lock itself
dominates completely, and both locks contend about equally.
When it does pay
Change one thing: make the reader hold the lock longer. Same locks, a loop inside the critical section:
go test -bench=LongRead -benchmem -run=^$ .
BenchmarkRWMutex_LongRead-11 106.5 ns/op
BenchmarkMutex_LongRead-11 206.1 ns/op
1.93×. Now the readers genuinely overlap, and RWMutex wins roughly in
proportion to how long they hold it.
So the rule is not “reads outnumber writes, therefore RWMutex”. It is:
RWMutexpays off in proportion to how long readers hold the lock. For a bare map lookup it is a wash. Reach for it when readers do real work.
Which leaves an honest question about the ORM. Its hot path — Get by type — is
a bare map lookup, so the RWMutex buys it almost nothing there. What justifies
it is the other readers:
func (r *Registry) GetAllTables() map[string]*schema.TableMetadata {
r.mu.RLock()
defer r.mu.RUnlock()
tables := make(map[string]*schema.TableMetadata)
maps.Copy(tables, r.names)
return tables
}
That copies the whole map under the read lock. The migration pipeline calls it, and it is exactly the long read the second benchmark describes. Course 07’s claim was right about the ORM and wrong about the reason, and I would not have noticed without running it.
The bug in lazy initialisation
Query builders do not register models up front. They call GetOrRegister, which
parses on first use:
func (r *Registry) GetOrRegister(t reflect.Type) *meta {
r.mu.RLock()
got, ok := r.m[t]
r.mu.RUnlock()
if ok {
return got
}
r.mu.Lock()
defer r.mu.Unlock()
m := parse(t) // ~500ns, 13 allocations
r.m[t] = m
return m
}
Read under RLock, and on a miss take the write lock and parse. That looks
correct and it is not.
Your turn. Release 200 goroutines at the same type simultaneously, count how
many parse, and count how many distinct pointers they get back. Use a channel
as a start barrier so they all hit the read check together, and make parse
sleep a couple of milliseconds so the window is visible.
no inner check: 2 missed, 2 parses, 2 distinct pointers
no inner check: 3 missed, 3 parses, 3 distinct pointers
no inner check: 1 missed, 1 parses, 1 distinct pointers
Two things to notice.
Only one to three of 200 goroutines miss. The window between RUnlock and
Lock is a few nanoseconds wide. That is why this class of bug ships: it almost
never happens, and when it does nothing fails loudly.
Each miss produces a distinct pointer. That is the real damage. Two callers
now hold different *TableMetadata for the same type, and the map keeps whichever
wrote last. The loser is holding an orphan — and if anything ever mutates
metadata after registration, those writes land somewhere nobody can read.
Note what the race detector says about this: nothing. go test -race is clean.
Every access is properly locked. This is a logic race, not a data race, and
course 07’s detector cannot see it.
The second check
The fix is to check again after acquiring the write lock:
r.mu.Lock()
defer r.mu.Unlock()
if got, ok := r.m[t]; ok { // someone registered while we waited
return got
}
m := parse(t)
inner check: 2 missed, 1 parses, 1 distinct pointers
Read that line carefully — two goroutines got past the read check, and only one parsed. The second acquired the write lock, found the entry the first had just written, and returned it. One pointer, one parse.
This is double-checked locking, and it is one of the few places the pattern is both correct and necessary in Go. The cheap read handles the 99.99% case; the second check handles the rest.
Predict: key by name or by type?
Two packages in one codebase, each with a User:
package admin; type User struct { ID, Email string }
package billing; type User struct { ID, StripeID string }
What does reflect.Type.Name() return for each, and what happens to a
map[string] keyed by it?
admin.User Name()="User" String()="admin.User"
billing.User Name()="User" String()="billing.User"
same Name()? true
same reflect.Type? false
map[string] keyed by Name() holds 1 entries for 2 models
map[reflect.Type] holds 2 entries for 2 models
Name() is the bare identifier, so both are "User" and the name-keyed map
silently collapses two models into one. reflect.Type is identity — it
carries the package — so it never collides. That is why the cache is keyed by
type, and it is course 08’s Type versus Kind distinction cashing out: you
want identity here, not shape.
What you just built
The real registry, with everything above in it:
type Registry struct {
mu sync.RWMutex
parser *schema.Parser
tables map[reflect.Type]*schema.TableMetadata
names map[string]*schema.TableMetadata
}
Two maps, deliberately. tables is keyed by reflect.Type for the query
builders, which always have a T. names is keyed by table name for the
migration pipeline, which reads SQL and only has a string. The second map has
the collision you just measured — two models that resolve to the same table name
would overwrite each other — and the ORM does not guard it, on the grounds that
two tables with one name is already broken.
The lock ratio is the giveaway about what this package is for: eight RLock
sites to three Lock sites. Writes happen once per model, ever. Reads happen
on every query, forever.
Build something
Turn course 10’s parser into a registry.
func NewRegistry() *Registry
func (r *Registry) GetOrRegister(model any) (*TableMetadata, error)
func (r *Registry) GetByName(name string) (*TableMetadata, error)
GetOrRegister takes any, so unwrap pointers and reject a non-struct with an
error rather than a panic — course 08’s Kind loop. Then write two tests:
- One parse under contention. Count parses with an
atomic.Int64, release 100 goroutines at the same type, assert the count is exactly 1. - Distinct pointers. Collect what every goroutine got back and assert there is exactly one unique pointer.
Then write the version without the inner check and run the tests repeatedly. Be ready for an uncomfortable result.
go test -race ./...
Check yourself
func (r *Registry) GetOrRegister(model any) (*TableMetadata, error) {
t := reflect.TypeOf(model)
for t != nil && t.Kind() == reflect.Pointer {
t = t.Elem()
}
if t == nil || t.Kind() != reflect.Struct {
return nil, fmt.Errorf("registry: want a struct, got %v", t)
}
r.mu.RLock()
got, ok := r.tables[t]
r.mu.RUnlock()
if ok {
return got, nil
}
r.mu.Lock()
defer r.mu.Unlock()
if got, ok := r.tables[t]; ok {
return got, nil
}
meta, err := r.parser.Parse(t)
if err != nil {
return nil, err
}
r.tables[t] = meta
r.names[meta.Name] = meta
return meta, nil
}
The validation happens before any lock. Unwrapping a pointer and checking
Kind needs no lock, and doing it first keeps the critical sections as short as
the benchmark says they should be.
parse runs while holding the write lock. That is 500 nanoseconds of
exclusive access, which feels wrong until you count how often it happens: once
per model. Parsing outside the lock and then taking it would mean two goroutines
could both parse — the same wasted work, plus more code.
The error return is why this is not sync.Once per type. Once cannot fail,
so a parse error would have to be stored and replayed, and you would be writing
this anyway with worse ergonomics.
Both tests pass most of the time against the broken version. With the inner
check removed, I measured the bug surfacing in 1 run out of 12, and adding a
two-millisecond sleep inside parse to widen the window only moved it to 1 in 8.
The parse count and the pointer count also move together — 2 parses always meant
2 pointers — so neither assertion is more sensitive than the other.
That is the real lesson of this section, and it is not a comfortable one. You cannot test your way to confidence about this bug. A hundred goroutines released at once still mostly serialise, because the first one through finishes before the scheduler has run the rest, and no amount of sleeping fixes that reliably.
Keep both tests — they document the invariant and they will occasionally catch a
regression. But the reason to write the second check is that it is correct, not
that a test demanded it. This is the category of bug you prevent by reasoning
about the window, and the only tool that helps afterwards is the
goroutineleak-style profile or a reader who knows the pattern.
Next
The query builder. You have metadata keyed by type and a generic entry point
from course 06 — next they meet, and Select[User](qb) starts producing real
SQL with real placeholders.