common

Documentation

Overview

Package common holds structalign's public contracts: the interfaces that decouple the CLI's layers and the plain data types those interfaces traffic in. Implementations live under internal/. Keeping the contracts here (rather than internal/) lets mockery generate mocks from a non-internal source.

Index

• func DiffStyleStrings() []string
• type Aligner
• type DiffStyle
  • func DiffStyleString(s string) (DiffStyle, error)
  • func DiffStyleValues() []DiffStyle
  • func (i DiffStyle) IsADiffStyle() bool
  • func (i DiffStyle) MarshalText() ([]byte, error)
  • func (i *DiffStyle) Set(value string) error
  • func (i DiffStyle) String() string
  • func (i *DiffStyle) UnmarshalText(text []byte) error
• type Finding
• type Inspector
• type Layout
• type LayoutField
• type Loader
• type Options
• type Sizes
• type Target

Functions

func DiffStyleStrings

func DiffStyleStrings() []string

DiffStyleStrings returns a slice of all String values of the enum

Types

type Aligner

type Aligner interface {
	Findings(t Target, opts Options) ([]Finding, error)
}

Aligner produces the struct-reordering findings for one Target, controlled by opts.

type DiffStyle

type DiffStyle uint8

DiffStyle selects how a Finding is rendered. enumer generates its String/parse/text-marshal helpers and a flag.Value implementation (Set), see diffstyle_enumer.go; the names map to "unified"/"side"/"none" via -trimprefix=Diff -transform=lower.

const (
	DiffUnified DiffStyle = iota
	DiffSide
	DiffNone
)

func DiffStyleString

func DiffStyleString(s string) (DiffStyle, error)

DiffStyleString retrieves an enum value from the enum constants string name. Throws an error if the param is not part of the enum.

func DiffStyleValues

func DiffStyleValues() []DiffStyle

DiffStyleValues returns all values of the enum

func (DiffStyle) IsADiffStyle

func (i DiffStyle) IsADiffStyle() bool

IsADiffStyle returns "true" if the value is listed in the enum definition. "false" otherwise

func (DiffStyle) MarshalText

func (i DiffStyle) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface for DiffStyle

func (*DiffStyle) Set

func (i *DiffStyle) Set(value string) error

Set allows flag and pflag libraries to set a value dynamically.

func (DiffStyle) String

func (i DiffStyle) String() string

func (*DiffStyle) UnmarshalText

func (i *DiffStyle) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface for DiffStyle

type Finding

type Finding struct {
	Fset       *token.FileSet
	Pos        token.Pos
	Name       string // enclosing named type, or "" for an anonymous struct
	TypeParams string // type-parameter names for a generic type, e.g. "[T]" (else "")
	Message    string // analyzer diagnostic (carries the size info)
	Original   string // current struct source ("struct{...}")
	Proposed   string // reordered struct from the analyzer's SuggestedFix
	OldSize    int64  // current struct size from the analyzer message (0 if unknown)
	NewSize    int64  // proposed (optimal) size from the analyzer message (0 if unknown)
}

Finding is one struct whose fields could be reordered to use less memory.

type Inspector

type Inspector interface {
	Layouts(t Target, opts Options) []Layout
}

Inspector computes the memory layout of each named struct in a Target, controlled by opts.

type Layout

type Layout struct {
	Name       string
	TypeParams string // for a generic type, e.g. "[T]" (else "")
	Note       string // optional caveat shown above the struct (e.g. the generic disclaimer)
	Total      int64
	Align      int64
	Padding    int64 // total padding across all fields
	Fields     []LayoutField
}

Layout is one named struct's computed memory layout.

type LayoutField

type LayoutField struct {
	Name    string
	Type    string
	Tag     string // raw struct tag without backticks, or ""
	Assume  string // for a generic field, the assumed type param(s), e.g. "T=any" (else "")
	Offset  int64
	Size    int64
	Align   int64
	Padding int64 // padding inserted after this field
}

LayoutField is one field's place in a struct's memory layout.

type Loader

type Loader interface {
	Load(patterns ...string) ([]Target, error)
}

Loader resolves Go package patterns (./..., import paths, directories, and "file=" queries) into typed Targets.

type Options

type Options struct {
	Patterns         []string // -type globs matched against named-type names (nil = all)
	KeepTags         bool     // preserve struct field tags in rendered text
	IncludeGenerated bool     // analyze structs in generated files (default: skip them)
	SkipCachePadded  bool     // skip structs containing a golang.org/x/sys/cpu.CacheLinePad field
}

Options controls which structs are analyzed and how findings are produced.

type Sizes

type Sizes interface {
	Sizeof(t types.Type) int64
	Alignof(t types.Type) int64
	Offsetsof(fields []*types.Var) []int64
}

Sizes abstracts go/types sizing so the target architecture is injectable: a real types.Sizes in production, a fixed types.SizesFor("gc","amd64") in tests (making golden output deterministic on any host arch). Its method set matches go/types.Sizes, so a common.Sizes value is directly assignable to a types.Sizes (e.g. analysis.Pass.TypesSizes).

type Target

type Target struct {
	PkgPath   string
	Fset      *token.FileSet
	Syntax    []*ast.File
	Types     *types.Package
	TypesInfo *types.Info
	Sizes     Sizes
	Errors    []error
}

Target is a loader-agnostic view of one typed Go package: everything the analyzer and the layout inspector need, without exposing go/packages.Package.