goreset generates Reset() methods for structs that are reused through a
sync.Pool or a free list: the value goes back to its zero state, but keeps
the memory it owns.
A pooled object has to be cleaned before reuse. *r = T{} is the fast way to
do it, and the wrong one: it drops every slice's backing array, forgets a
reusable *time.Timer, and does not compile for a struct holding a mutex.
A hand-written Reset keeps all of that — until a new field is added and
forgotten there. goreset writes the method from the struct definition, so
it is always complete, and chooses the cheapest form for the type:
// Code generated by goreset; DO NOT EDIT.
// Reset zeroes r in one assignment and gives the slices their arrays back.
func (r *Request) Reset() {
clear(r.Data)
keepData := r.Data[:0]
keepTimer := r.Timer
*r = Request{}
r.Data = keepData
r.Mask = ^uint32(0)
r.Timer = keepTimer
if r.Timer != nil {
r.Timer.Stop()
}
}Everything is reset unless a tag says otherwise. Pooled state goes wrong in
the field nobody thought of: a flag like "skip the body" set for one request
and still set for the next one that takes the object from the pool. A
hand-written Reset lists what to clear and misses what it forgot; a
generated one lists only what to keep, so a new field is cleared from the
first go generate on.
| Field | Reset |
|---|---|
| slice | clear(s); s = s[:0] — the backing array is kept; when the elements hold pointers, clear(s[:cap(s)]), so the array keeps nothing alive |
pointer, unsafe.Pointer, map, chan, interface, func |
nil (an interface too when its methods include Reset()) |
| numbers, bool, string, arrays, plain structs | zero value |
value with its own Reset() |
r.F.Reset() |
pointer with its own Reset() |
kept; r.F.Reset() when not nil |
sync/atomic types |
Store(0) / Store(false) / Store(nil); atomic.Value is set to its zero value |
sync.* (Mutex, WaitGroup, Pool...) |
left alone |
_ (padding) |
left out: field by field it is not touched, bulk mode zeroes it |
type parameter T |
*new(T), its zero value, even when its constraint has Reset(): the call could not be guarded against nil |
type parameter P that only pointers satisfy and that has Reset() (P interface{ *T; Reset() }) |
like a pointer with its own Reset(): kept; r.F.Reset() when not nil |
Struct tags change the treatment of a field:
| Tag | Effect |
|---|---|
reset:"-" |
the field is left as it is |
reset:"value=EXPR" |
set to EXPR instead of zero, e.g. value=^uint32(0) |
reset:"value=pkg.Const,import=example.com/pkg" |
the same with an import the expression needs |
reset:"call=Method" |
kept; r.F.Method() is called (call=Stop for a *time.Timer), when not nil if the field can be nil; a type parameter that is not only pointers cannot be checked for nil, so the method is called whatever the value |
reset:"release=Func" |
pointer with Reset(): Func(r.F) is called and the field set to nil |
reset:"maxcap=N" |
slice: kept and cleared as usual while cap is at most N, set to nil (the array let go, not cleared) above it; N is a constant integer expression of the package, e.g. maxcap=64<<10 |
Bulk: the fields to keep are saved, the struct is zeroed in one
assignment, the kept fields are put back. One memclr for the whole struct,
no per-field code for the zeroed ones.
Field by field: one statement per field; sync fields are not touched.
The mode is chosen per type by a cost model, in units of one field store:
| bulk | field by field | |
|---|---|---|
| the struct | memclr: 1 per 16 bytes |
— |
| plain field (number, pointer, string, atomic...) | 0 | 1 |
| slice | 3 (clear, keep, restore) | 2 (clear, reslice) |
slice with maxcap= |
4 | 3 |
value with Reset() |
2 + 2 per 16 bytes (copied out and back) | 1 (the call) |
pointer with Reset(), call=, reset:"-" |
2 (keep, restore) | 1 |
value= |
1 | 1 |
array, struct without Reset() |
0 | 1 per 16 bytes |
The cheaper mode is generated; a sync field forces field-wise mode whatever
the costs, and so does a field bulk mode would keep by copy (reset:"-",
call= on a value, a value with Reset()) whose value holds a lock: a
sync or sync/atomic value, or a type go vet treats as a lock. The constants were fitted on two real structs (700 bytes / 95
fields: both modes equal; 2400 bytes / 74 fields: field-wise 2.5x faster) —
a model, not a measurement, so a struct near the break-even point is worth a
benchmark of its own.
The comment of the generated method says which mode and why:
// Reset zeroes r field by field, not in one assignment:
// - zeroing all 2400 bytes and restoring 39 fields costs 314, resetting the 74 fields one by one costs 162and the generator says so on stderr too, with what would change the outcome:
goreset: wrote reqvars_reset.gen.go
goreset: ReqVars is reset field by field; for one assignment:
- ReqVars: one assignment would zero all 2400 bytes and restore 39 fields (cost 314) where resetting the 74 fields one by one costs 162; fewer slices and kept values, or a smaller struct, would turn that around
For a lock the hint is to move it behind a pointer or out of the pooled value.
Package.Analyze
returns the mode, both costs and the hints to other tools.
go get -tool github.com/darxnet/goreset/cmd/goresetRequires Go 1.24 (go get -tool). No dependencies: the package is loaded with
go list -export and go/importer from the standard library.
Put the directive next to the type and run go generate:
//go:generate go tool goreset -type=Request,Response
type Request struct {
Data []byte
Timer *time.Timer `reset:"call=Stop"`
Mask uint32 `reset:"value=^uint32(0)"`
Mu sync.Mutex
}This writes request_reset.gen.go and response_reset.gen.go in the same
package. -dir points the generator at another package.
The generator is also a library — goreset.Load
and Package.Generate —
for tools that want the source without the file.
- It must run without concurrent users of the value: atomics are stored, not swapped, and bulk mode copies the struct.
- Slices keep their capacity. A buffer that may grow very large once should
be tagged
reset:"maxcap=N", so an array pastNis let go instead of kept for every later use; anything else that must not keep memory between uses is taggedreset:"-"and handled by hand, or released throughrelease=. - A nested value's
Reset()is called after the bulk assignment, so it sees its own state, not zeroes. - A generic struct gets one
Resetfor all its instantiations (func (r *Pair[K, V]) Reset()). The cost model sizes each type parameter as one pointer, so the choice of mode is a guess for the instantiations that are much larger.
The sibling modules follow the same rule — nothing allocated on the hot path, the zero value ready to use:
- goshard — sharded, lock-based concurrent map for high-churn data: stores allocate nothing
- gosync — generic concurrent map with
sync.Mapsemantics and no interface boxing, for read-mostly data - gocopy — generates
CopyFrom/Copythat reuse the destination's memory instead of allocating
Apache License 2.0. See LICENSE for details.