Functional Options — Optimize¶

// Pre-build the option list once at package init.
var defaultSpanOpts = []Option{
    WithService("checkout"),
    WithComponent("api"),
    WithSampleRate(0.01),
    WithTimeout(5 * time.Second),
}

func handleRequest(name string) *Span {
    return NewSpan(name, defaultSpanOpts...)
}

var baseSpanOpts = []Option{
    WithComponent("api"),
    WithSampleRate(0.01),
    WithTimeout(5 * time.Second),
}

func handleRequest(name, service string) *Span {
    return NewSpan(name, append(baseSpanOpts, WithService(service))...)
}

func handleRequest(name, service string) *Span {
    opts := [...]Option{
        WithService(service),
        baseSpanOpts[0], baseSpanOpts[1], baseSpanOpts[2],
    }
    return NewSpan(name, opts[:]...)
}

var optPool = sync.Pool{
    New: func() any {
        s := make([]Option, 0, 8)
        return &s
    },
}

func Log(level int, msg string, ctx map[string]any) {
    optsPtr := optPool.Get().(*[]Option)
    opts := (*optsPtr)[:0]
    for k, v := range ctx {
        opts = append(opts, WithField(k, v))
    }
    _ = NewEntry(level, opts...)
    *optsPtr = opts[:0]
    optPool.Put(optsPtr)
}

func Log(level int, msg string, ctx map[string]any) {
    var buf [8]Option
    opts := buf[:0]
    for k, v := range ctx {
        opts = append(opts, WithField(k, v))
        if len(opts) == cap(buf) { break }
    }
    _ = NewEntry(level, opts...)
}

type Option func(*Config)

func WithA(v int) Option { return func(c *Config) { c.a = v } }
func WithB(v int) Option { return func(c *Config) { c.b = v } }
// ...

func New(opts ...Option) *Config {
    c := &Config{}
    for _, o := range opts {
        o(c)
    }
    return c
}

// internal_new.go (same package)
// Direct construction. Used only from within the package.
func newServerDirect() *Server {
    return &Server{
        addr:         ":8080",
        readTimeout:  30 * time.Second,
        writeTimeout: 30 * time.Second,
        maxConns:     1000,
        logger:       log.Default(),
        bufferSize:   4096,
    }
}

func defaultServer() *Server {
    return newServerDirect()
}

func defaults() *Server {
    return &Server{
        readTimeout:  30 * time.Second,
        writeTimeout: 30 * time.Second,
        maxConns:     1000,
        logger:       log.Default(),
        bufferSize:   4096,
    }
}

func NewServer(addr string, opts ...Option) *Server {
    s := defaults()
    s.addr = addr
    for _, o := range opts { o(s) }
    return s
}

func newServerDirect() *Server {
    s := defaults()
    s.addr = ":8080"
    return s
}

// Filter once at the source.
func filterNils(opts []Option) []Option {
    out := opts[:0]
    for _, o := range opts {
        if o != nil {
            out = append(out, o)
        }
    }
    return out
}

// At config load time, not per-construction
var validOpts = filterNils(loadOptionsFromConfig())

func NewServer(addr string, opts ...Option) *Server {
    s := &Server{addr: addr}
    for _, opt := range opts {
        opt(s)   // no nil check
    }
    return s
}

// hot path
func handler() *Server {
    return NewSenseValidOpts(validOpts)
}

// Compose 50 options into a single closure once.
func Compose(opts ...Option) Option {
    return func(s *Server) {
        for _, o := range opts {
            o(s)
        }
    }
}

var composedFifty = Compose(fiftyOpts...)

func BenchmarkComposed(b *testing.B) {
    for i := 0; i < b.N; i++ {
        _ = NewServer(":8080", composedFifty)
    }
}

// Compose lets the compiler inline the inner loop in some cases.
// More importantly, it reduces the *variadic slice* to a single Option,
// which avoids the slice allocation if you previously had to build one.
func handler(extra Option) *Server {
    return NewServer(":8080", composedFifty, extra)
    // vs:
    // opts := append(fiftyOpts, extra)  // allocation
    // return NewServer(":8080", opts...)
}

// Document that the caller must not mutate cfg after passing it.
func WithTLS(cfg *tls.Config) Option {
    return func(s *Server) {
        s.tls = cfg  // share the pointer
    }
}

func WithTLS(cfg *tls.Config) Option {
    // Snapshot the fields we care about, not the whole struct.
    snapshot := &tls.Config{
        MinVersion:   cfg.MinVersion,
        MaxVersion:   cfg.MaxVersion,
        Certificates: cfg.Certificates,  // slice header copy is cheap
    }
    return func(s *Server) {
        s.tls = snapshot
    }
}

type Server struct {
    metricsAddr  string
    metricsOnce  sync.Once
    metrics      *metrics.Collector
}

// Option stores the address only.
func WithMetrics(addr string) Option {
    return func(s *Server) { s.metricsAddr = addr }
}

// Lazily initialize when first used.
func (s *Server) Metrics() *metrics.Collector {
    s.metricsOnce.Do(func() {
        if s.metricsAddr != "" {
            s.metrics = metrics.New(s.metricsAddr)
        }
    })
    return s.metrics
}

// Eager for required subsystems, lazy for optional ones.
func NewServer(addr string, opts ...Option) (*Server, error) {
    s := &Server{}
    for _, o := range opts { o(s) }
    // Eagerly init *required* subsystems
    if err := s.connectDB(); err != nil { return nil, err }
    // Defer optional ones
    return s, nil
}

// Validate the option set ONCE, off the hot path.
type ValidatedOpts struct {
    opts []Option
}

func Validate(opts ...Option) (*ValidatedOpts, error) {
    // Run a probe construction to detect dependency errors.
    probe := &Server{}
    for _, o := range opts { o(probe) }
    if probe.tlsCert == nil && probe.tlsKey != nil {
        return nil, errors.New("WithKey requires WithCert")
    }
    // ...rest of checks
    return &ValidatedOpts{opts: opts}, nil
}

// Hot-path constructor skips validation.
func NewServerValidated(addr string, v *ValidatedOpts) *Server {
    s := &Server{addr: addr}
    for _, o := range v.opts { o(s) }
    return s
}

// Public, validates every time
func NewServer(addr string, opts ...Option) (*Server, error) { ... }

// Internal, skip validation. Use only with opts from a trusted source.
func newServerUnchecked(addr string, opts []Option) *Server {
    s := &Server{addr: addr}
    for _, o := range opts { o(s) }
    return s
}

// Pre-compute the configured server once.
var snapshot = func() Server {
    s := &Server{}
    for _, o := range fiveStdOpts { o(s) }
    return *s   // dereference to a value
}()

func handler(addr string) *Server {
    s := snapshot   // struct copy, on the stack
    s.addr = addr
    return &s
}

// BUG: every server shares the same logger
var snapshot = func() Server {
    s := &Server{logger: log.New(...)}
    return *s
}()

func handler(addr string) *Server {
    s := snapshot
    s.logger.SetPrefix("server1:")  // mutates snapshot.logger too!
    return &s
}

type Server struct {
    addr        string         // value
    timeout     time.Duration  // value
    bufferSize  int            // value
    logger      *log.Logger    // pointer — DO NOT snapshot
}

var configSnapshot = struct {
    timeout    time.Duration
    bufferSize int
}{
    timeout:    30 * time.Second,
    bufferSize: 4096,
}

func handler(addr string, logger *log.Logger) *Server {
    return &Server{
        addr:       addr,
        timeout:    configSnapshot.timeout,
        bufferSize: configSnapshot.bufferSize,
        logger:     logger,
    }
}

//go:generate go run gen.go

// Specialized constructor — generated.
// Equivalent to NewServer(addr, WithReadTimeout(5s), WithWriteTimeout(10s), WithMaxConns(1000))
func NewServerStdAPI(addr string) *Server {
    return &Server{
        addr:         addr,
        readTimeout:  5 * time.Second,
        writeTimeout: 10 * time.Second,
        maxConns:     1000,
        logger:       defaultLogger,
        bufferSize:   defaultBufferSize,
    }
}

func handler(addr string) *Server {
    return NewServerStdAPI(addr)
}

// gen.go (run with go generate)
package main

import (
    "os"
    "text/template"
)

type spec struct {
    Name  string
    Addr  string
    Read  string
    Write string
    Max   int
}

const tmpl = `// Code generated. DO NOT EDIT.
package server

import "time"

func New{{.Name}}(addr string) *Server {
    return &Server{
        addr:         addr,
        readTimeout:  {{.Read}},
        writeTimeout: {{.Write}},
        maxConns:     {{.Max}},
        logger:       defaultLogger,
        bufferSize:   defaultBufferSize,
    }
}
`

func main() {
    specs := []spec{
        {Name: "ServerStdAPI", Read: "5*time.Second", Write: "10*time.Second", Max: 1000},
        {Name: "ServerInternalRPC", Read: "1*time.Second", Write: "2*time.Second", Max: 100},
    }
    t := template.Must(template.New("c").Parse(tmpl))
    f, _ := os.Create("generated_constructors.go")
    defer f.Close()
    for _, s := range specs { t.Execute(f, s) }
}

type Option interface{ apply(*Server) }

type timeoutOpt time.Duration
func (o timeoutOpt) apply(s *Server) { s.timeout = time.Duration(o) }

func WithTimeout(d time.Duration) Option { return timeoutOpt(d) }

type bigOpt struct{ a, b int64 }
func (o bigOpt) apply(s *Server) { s.a = o.a; s.b = o.b }

func WithBig(a, b int64) Option { return bigOpt{a, b} }