Involved Source Filescodes.godecoder.go
Package pkgbits implements low-level coding abstractions for
Unified IR's export data format.
At a low-level, a package is a collection of bitstream elements.
Each element has a "kind" and a dense, non-negative index.
Elements can be randomly accessed given their kind and index.
Individual elements are sequences of variable-length values (e.g.,
integers, booleans, strings, go/constant values, cross-references
to other elements). Package pkgbits provides APIs for encoding and
decoding these low-level values, but the details of mapping
higher-level Go constructs into elements is left to higher-level
abstractions.
Elements may cross-reference each other with "relocations." For
example, an element representing a pointer type has a relocation
referring to the element type.
Go constructs may be composed as a constellation of multiple
elements. For example, a declared function may have one element to
describe the object (e.g., its name, type, position), and a
separate element to describe its function body. This allows readers
some flexibility in efficiently seeking or re-reading data (e.g.,
inlining requires re-reading the function body for each inlined
call, without needing to re-read the object-level details).
This is a copy of internal/pkgbits in the Go implementation.
encoder.goflags.goframes_go17.goreloc.gosupport.gosync.gosyncmarker_string.go
Package-Level Type Names (total 13, in which 12 are exported)
/* sort exporteds by: | */
A Code is an enum value that can be encoded into bitstreams.
Code types are preferable for enum types, because they allow
Decoder to detect desyncs.
Marker returns the SyncMarker for the Code's dynamic type.
Value returns the Code's ordinal value.
CodeObjCodeTypeCodeVal
func (*Encoder).Code(c Code)
A Decoder provides methods for decoding an individual element's
bitstream data.
Datastrings.ReaderIdxIndexRelocs[]RelocEntcommon*PkgDecoderkRelocKind
Bool decodes and returns a bool value from the element bitstream.
Code decodes a Code value from the element bitstream and returns
its ordinal value. It's the caller's responsibility to convert the
result to an appropriate Code type.
TODO(mdempsky): Ideally this method would have signature "Code[T
Code] T" instead, but we don't allow generic methods and the
compiler can't depend on generics yet anyway.
Int decodes and returns an int value from the element bitstream.
Int64 decodes and returns an int64 value from the element bitstream.
Len decodes and returns a non-negative int value from the element bitstream.
Reloc decodes a relocation of expected section k from the element
bitstream and returns an index to the referenced element.
String decodes and returns a string value from the element
bitstream.
Strings decodes and returns a variable-length slice of strings from
the element bitstream.
Sync decodes a sync marker from the element bitstream and asserts
that it matches the expected marker.
If r.common.sync is false, then Sync is a no-op.
Uint decodes and returns a uint value from the element bitstream.
Uint64 decodes and returns a uint64 value from the element bitstream.
Value decodes and returns a constant.Value from the element
bitstream.
(*Decoder) bigFloat() *big.Float(*Decoder) bigInt() *big.Int(*Decoder) checkErr(err error)(*Decoder) rawReloc(k RelocKind, idx int) Index(*Decoder) rawUvarint() uint64(*Decoder) rawVarint() int64(*Decoder) scalar() constant.Value
*Decoder : expvar.Var
*Decoder : fmt.Stringer
*Decoder : context.stringer
*Decoder : github.com/aws/smithy-go/middleware.stringer
*Decoder : runtime.stringer
func (*PkgDecoder).NewDecoder(k RelocKind, idx Index, marker SyncMarker) Decoder
func (*PkgDecoder).NewDecoderRaw(k RelocKind, idx Index) Decoder
func (*PkgDecoder).TempDecoder(k RelocKind, idx Index, marker SyncMarker) Decoder
func (*PkgDecoder).TempDecoderRaw(k RelocKind, idx Index) Decoder
func (*PkgDecoder).RetireDecoder(d *Decoder)
An Encoder provides methods for encoding an individual element's
bitstream data.
// accumulated element bitstream data
// index within relocation section
RelocMapmap[RelocEnt]uint32Relocs[]RelocEntencodingRelocHeaderboolkRelocKindp*PkgEncoder
Bool encodes and writes a bool value into the element bitstream,
and then returns the bool value.
For simple, 2-alternative encodings, the idiomatic way to call Bool
is something like:
if w.Bool(x != 0) {
// alternative #1
} else {
// alternative #2
}
For multi-alternative encodings, use Code instead.
Code encodes and writes a Code value into the element bitstream.
Flush finalizes the element's bitstream and returns its Index.
Int encodes and writes an int value into the element bitstream.
Int64 encodes and writes an int64 value into the element bitstream.
Len encodes and writes a non-negative int value into the element bitstream.
Reloc encodes and writes a relocation for the given (section,
index) pair into the element bitstream.
Note: Only the index is formally written into the element
bitstream, so bitstream decoders must know from context which
section an encoded relocation refers to.
String encodes and writes a string value into the element
bitstream.
Internally, strings are deduplicated by adding them to the strings
section (if not already present), and then writing a relocation
into the element bitstream.
Strings encodes and writes a variable-length slice of strings into
the element bitstream.
(*Encoder) Sync(m SyncMarker)
Uint encodes and writes a uint value into the element bitstream.
Uint64 encodes and writes a uint64 value into the element bitstream.
Value encodes and writes a constant.Value into the element
bitstream.
(*Encoder) bigFloat(v *big.Float)(*Encoder) bigInt(v *big.Int)(*Encoder) checkErr(err error)(*Encoder) rawReloc(r RelocKind, idx Index) int(*Encoder) rawUvarint(x uint64)(*Encoder) rawVarint(x int64)(*Encoder) scalar(val constant.Value)
func (*PkgEncoder).NewEncoder(k RelocKind, marker SyncMarker) Encoder
func (*PkgEncoder).NewEncoderRaw(k RelocKind) Encoder
A PkgDecoder provides methods for decoding a package's Unified IR
export data.
elemData is the full data payload of the encoded package.
Elements are densely and contiguously packed together.
The last 8 bytes of elemData are the package fingerprint.
elemEnds stores the byte-offset end positions of element
bitstreams within elemData.
For example, element I's bitstream data starts at elemEnds[I-1]
(or 0, if I==0) and ends at elemEnds[I].
Note: elemEnds is indexed by absolute indices, not
section-relative indices.
elemEndsEnds stores the index-offset end positions of relocation
sections within elemEnds.
For example, section K's end positions start at elemEndsEnds[K-1]
(or 0, if K==0) and end at elemEndsEnds[K].
pkgPath is the package path for the package to be decoded.
TODO(mdempsky): Remove; unneeded since CL 391014.
scratchRelocEnt[]RelocEnt
sync indicates whether the file uses sync markers.
version is the file format version.
AbsIdx returns the absolute index for the given (section, index)
pair.
DataIdx returns the raw element bitstream for the given (section,
index) pair.
Fingerprint returns the package fingerprint.
NewDecoder returns a Decoder for the given (section, index) pair,
and decodes the given SyncMarker from the element bitstream.
NewDecoderRaw returns a Decoder for the given (section, index) pair.
Most callers should use NewDecoder instead.
NumElems returns the number of elements in section k.
PeekObj returns the package path, object name, and CodeObj for the
specified object index.
PeekPkgPath returns the package path for the specified package
index.
PkgPath returns the package path for the package
TODO(mdempsky): Remove; unneeded since CL 391014.
(*PkgDecoder) RetireDecoder(d *Decoder)
StringIdx returns the string value for the given string index.
SyncMarkers reports whether pr uses sync markers.
TempDecoder returns a Decoder for the given (section, index) pair,
and decodes the given SyncMarker from the element bitstream.
If possible the Decoder should be RetireDecoder'd when it is no longer
needed, this will avoid heap allocations.
(*PkgDecoder) TempDecoderRaw(k RelocKind, idx Index) Decoder
TotalElems returns the total number of elements across all sections.
func NewPkgDecoder(pkgPath, input string) PkgDecoder
func golang.org/x/tools/internal/gcimporter.readUnifiedPackage(fset *token.FileSet, ctxt *types.Context, imports map[string]*types.Package, input PkgDecoder) *types.Package
A PkgEncoder provides methods for encoding a package's Unified IR
export data.
elems holds the bitstream for previously encoded elements.
stringsIdx maps previously encoded strings to their index within
the RelocString section, to allow deduplication. That is,
elems[RelocString][stringsIdx[s]] == s (if present).
syncFrames is the number of frames to write at each sync
marker. A negative value means sync markers are omitted.
DumpTo writes the package's encoded data to out0 and returns the
package fingerprint.
NewEncoder returns an Encoder for a new element within the given
section, and encodes the given SyncMarker as the start of the
element bitstream.
NewEncoderRaw returns an Encoder for a new element within the given
section.
Most callers should use NewEncoder instead.
StringIdx adds a string value to the strings section, if not
already present, and returns its index.
SyncMarkers reports whether pw uses sync markers.
func NewPkgEncoder(syncFrames int) PkgEncoder
A relocEnt (relocation entry) is an entry in an element's local
reference table.
TODO(mdempsky): Rename this too.
IdxIndexKindRelocKind
Package-Level Functions (total 7, in which 2 are exported)
NewPkgDecoder returns a PkgDecoder initialized to read the Unified
IR export data from input. pkgPath is the package path for the
compilation unit that produced the export data.
TODO(mdempsky): Remove pkgPath parameter; unneeded since CL 391014.
NewPkgEncoder returns an initialized PkgEncoder.
syncFrames is the number of caller frames that should be serialized
at Sync points. Serializing additional frames results in larger
export data files, but can help diagnosing desync errors in
higher-level Unified IR reader/writer code. If syncFrames is
negative, then sync markers are omitted entirely.
fmtFrames formats a backtrace for reporting reader/writer desyncs.
readUvarint is a type-specialized copy of encoding/binary.ReadUvarint.
This avoids the interface conversion and thus has better escape properties,
which flows up the stack.
walkFrames calls visit for each call frame represented by pcs.
pcs should be a slice of PCs, as returned by runtime.Callers.
Package-Level Variables (total 2, neither is exported)