sync.Once & Singleton Patterns

sync.Once runs a function exactly one time, even when many goroutines call it concurrently.

Teams use it for lazy initialization of expensive resources while avoiding init() ordering hazards.

Summary

A singleton exposes one shared instance for the whole program.

Go can implement that with package-level variables, but idiomatic production code prefers explicit dependency injection and reserves sync.Once for cases like registering codecs or loading TLS roots where a single lazy setup is unavoidable.

The stdlib uses sync.Once internally for one-time initialization; your application code should use it sparingly and document why globals are justified.

Recipe

Quick-reference recipe card - copy-paste ready.

var (
    parser *regexp.Regexp
    once   sync.Once
)
 
func emailPattern() *regexp.Regexp {
    once.Do(func() {
        parser = regexp.MustCompile(`^[^@]+@[^@]+\.[^@]+$`)
    })
    return parser
}

When to reach for this:

• One-time expensive compile/load (regex, schema, default HTTP transport)
• Lazy init when main cannot easily pass dependencies into deep call stacks
• Library-internal caches that must be process-wide

Working Example

package metrics
 
import (
    "sync"
 
    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promauto"
)
 
type Registry struct {
    requests *prometheus.CounterVec
}
 
var (
    defaultReg *Registry
    once       sync.Once
)
 
func Default() *Registry {
    once.Do(func() {
        defaultReg = &Registry{
            requests: promauto.NewCounterVec(
                prometheus.CounterOpts{Name: "http_requests_total", Help: "HTTP requests"},
                []string{"route", "code"},
            ),
        }
    })
    return defaultReg
}
 
func (r *Registry) Inc(route, code string) {
    r.requests.WithLabelValues(route, code).Inc()
}
 
func ExampleUsage() {
    Default().Inc("/health", "200")
}

What this demonstrates:

• once.Do initializes defaultReg on first Default() call
• Subsequent calls return the same pointer without locking on the hot path
• Exported Default() documents the global access point

Deep Dive

How It Works

• sync.Once stores a done flag and mutex
• First Do runs f; concurrent waiters block until completion
• After completion, Do becomes a fast atomic load
• If f panics, Once is stuck - do not panic inside Do

sync.Once versus init()

Singleton Trade-offs

Go Notes

// Prefer this in application code:
func NewAPI(reg *metrics.Registry) *API { return &API{reg: reg} }
 
// In main:
reg := metrics.NewRegistry()
api := NewAPI(reg)

• Resetting globals in tests requires build tags or dependency injection
• Do not call once.Do with different functions - only the first runs
• For process-wide http.DefaultClient, prefer explicit client with timeout

Gotchas

• Panics inside once.Do - Once never retries; package stays broken. Fix: validate before Do or panic only on programmer errors you accept as fatal.
• Singleton database pool - Tests race on shared state; migrations become global. Fix: pass *sql.DB from main or test helper.
• init() dials services - Importing package in tests hits production. Fix: lazy sync.Once or no init networking.
• Hidden Default() everywhere - Signatures omit dependencies; fakes impossible. Fix: inject interface; keep Default() for demos only.
• Double-checked locking by hand - Easy to get wrong before Go 1.21 memory model assumptions. Fix: use sync.Once instead of custom atomics.
• Once per instance confusion - Once must live on the struct if each instance initializes separately. Fix: package-level Once only for true singletons.

Alternatives

FAQs

Related

• Constructor Functions & Package APIs - explicit New wiring
• Go Patterns Basics - sync.Once introductory example
• Common Anti-Patterns in Go Codebases - init() and global state
• Go Idioms: Composition Over Inheritance - dependency injection bias

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify at build).