pkgbits
packagestandard library
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Report a Vulnerability
Documentation¶
Overview¶
Package pkgbits implements low-level coding abstractions for Unified IR's(UIR) binary export data format.
At a low-level, the exported objects of a package are encoded as a bytearray. This array contains byte representations of primitive, potentiallyvariable-length values, such as integers, booleans, strings, and constants.
Additionally, the array may contain values which denote indices in the bytearray itself. These are termed "relocations" and allow for references.
The details of mapping high-level Go constructs to primitives are left toother packages.
Index¶
- type AbsElemIdx
- type Code
- type CodeObj
- type CodeType
- type CodeVal
- type Decoder
- func (r *Decoder) Bool() bool
- func (r *Decoder) Code(mark SyncMarker) int
- func (r *Decoder) Int() int
- func (r *Decoder) Int64() int64
- func (r *Decoder) Len() int
- func (r *Decoder) Reloc(k SectionKind) RelElemIdx
- func (r *Decoder) String() string
- func (r *Decoder) Strings() []string
- func (r *Decoder) Sync(mWant SyncMarker)
- func (r *Decoder) Uint() uint
- func (r *Decoder) Uint64() uint64
- func (r *Decoder) Value() constant.Value
- func (w *Decoder) Version() Version
- type Encoder
- func (w *Encoder) Bool(b bool) bool
- func (w *Encoder) Code(c Code)
- func (w *Encoder) Flush() RelElemIdx
- func (w *Encoder) Int(x int)
- func (w *Encoder) Int64(x int64)
- func (w *Encoder) Len(x int)
- func (w *Encoder) Reloc(k SectionKind, idx RelElemIdx)
- func (w *Encoder) String(s string)
- func (w *Encoder) StringRef(idx RelElemIdx)
- func (w *Encoder) Strings(ss []string)
- func (w *Encoder) Sync(m SyncMarker)
- func (w *Encoder) Uint(x uint)
- func (w *Encoder) Uint64(x uint64)
- func (w *Encoder) Value(val constant.Value)
- func (w *Encoder) Version() Version
- type Field
- type Index
- type PkgDecoder
- func (pr *PkgDecoder) AbsIdx(k SectionKind, idx RelElemIdx) int
- func (pr *PkgDecoder) DataIdx(k SectionKind, idx RelElemIdx) string
- func (pr *PkgDecoder) Fingerprint() [8]byte
- func (pr *PkgDecoder) NewDecoder(k SectionKind, idx RelElemIdx, marker SyncMarker) Decoder
- func (pr *PkgDecoder) NewDecoderRaw(k SectionKind, idx RelElemIdx) Decoder
- func (pr *PkgDecoder) NumElems(k SectionKind) int
- func (pr *PkgDecoder) PeekObj(idx RelElemIdx) (string, string, CodeObj)
- func (pr *PkgDecoder) PeekPkgPath(idx RelElemIdx) string
- func (pr *PkgDecoder) PkgPath() string
- func (pr *PkgDecoder) RetireDecoder(d *Decoder)
- func (pr *PkgDecoder) StringIdx(idx RelElemIdx) string
- func (pr *PkgDecoder) SyncMarkers() bool
- func (pr *PkgDecoder) TempDecoder(k SectionKind, idx RelElemIdx, marker SyncMarker) Decoder
- func (pr *PkgDecoder) TempDecoderRaw(k SectionKind, idx RelElemIdx) Decoder
- func (pr *PkgDecoder) TotalElems() int
- type PkgEncoder
- type RefTableEntry
- type RelElemIdx
- type SectionKind
- type SyncMarker
- type Version
Constants¶
This section is empty.
Variables¶
This section is empty.
Functions¶
This section is empty.
Types¶
typeAbsElemIdx¶added ingo1.25.0
type AbsElemIdx =uint32
An AbsElemIdx, or absolute element index, is an index into the elementsthat is not relative to some other index.
typeCode¶
type Code interface {// Marker returns the SyncMarker for the Code's dynamic type.Marker()SyncMarker// Value returns the Code's ordinal value.Value()int}A Code is an enum value that can be encoded into bitstreams.
Code types are preferable for enum types, because they allowDecoder to detect desyncs.
typeCodeObj¶
type CodeObjint
A CodeObj distinguishes among go/types.Object encodings.
func (CodeObj)Marker¶
func (cCodeObj) Marker()SyncMarker
typeCodeType¶
type CodeTypeint
A CodeType distinguishes among go/types.Type encodings.
func (CodeType)Marker¶
func (cCodeType) Marker()SyncMarker
typeCodeVal¶
type CodeValint
A CodeVal distinguishes among go/constant.Value encodings.
func (CodeVal)Marker¶
func (cCodeVal) Marker()SyncMarker
typeDecoder¶
type Decoder struct {Relocs []RefTableEntryDatastrings.ReaderIdxRelElemIdx// contains filtered or unexported fields}A Decoder provides methods for decoding an individual element'sbitstream data.
func (*Decoder)Code¶
func (r *Decoder) Code(markSyncMarker)int
Code decodes a Code value from the element bitstream and returnsits ordinal value. It's the caller's responsibility to convert theresult to an appropriate Code type.
TODO(mdempsky): Ideally this method would have signature "Code[TCode] T" instead, but we don't allow generic methods and thecompiler can't depend on generics yet anyway.
func (*Decoder)Reloc¶
func (r *Decoder) Reloc(kSectionKind)RelElemIdx
Reloc decodes a relocation of expected section k from the elementbitstream and returns an index to the referenced element.
func (*Decoder)Strings¶
Strings decodes and returns a variable-length slice of strings fromthe element bitstream.
func (*Decoder)Sync¶
func (r *Decoder) Sync(mWantSyncMarker)
Sync decodes a sync marker from the element bitstream and assertsthat it matches the expected marker.
If EnableSync is false, then Sync is a no-op.
typeEncoder¶
type Encoder struct {Relocs []RefTableEntryRelocMap map[RefTableEntry]uint32Databytes.Buffer// accumulated element bitstream dataIdxRelElemIdx// index within relocation section// contains filtered or unexported fields}An Encoder provides methods for encoding an individual element'sbitstream data.
func (*Encoder)Bool¶
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 Boolis something like:
if w.Bool(x != 0) {// alternative #1} else {// alternative #2}For multi-alternative encodings, use Code instead.
func (*Encoder)Flush¶
func (w *Encoder) Flush()RelElemIdx
Flush finalizes the element's bitstream and returns itsRelElemIdx.
func (*Encoder)Reloc¶
func (w *Encoder) Reloc(kSectionKind, idxRelElemIdx)
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 elementbitstream, so bitstream decoders must know from context whichsection an encoded relocation refers to.
func (*Encoder)String¶
String encodes and writes a string value into the elementbitstream.
Internally, strings are deduplicated by adding them to the stringssection (if not already present), and then writing a relocationinto the element bitstream.
func (*Encoder)StringRef¶added ingo1.20
func (w *Encoder) StringRef(idxRelElemIdx)
StringRef writes a reference to the given index, which must be apreviously encoded string value.
func (*Encoder)Strings¶
Strings encodes and writes a variable-length slice of strings intothe element bitstream.
func (*Encoder)Sync¶
func (w *Encoder) Sync(mSyncMarker)
typeField¶added ingo1.24.0
type Fieldint
Field denotes a unit of data in the serialized unified IR bitstream.It is conceptually a like field in a structure.
We only really need Fields when the data may or may not be presentin a stream based on the Version of the bitstream.
Unlike much of pkgbits, Fields are not serialized andcan change values as needed.
const (// Flags in a uint32 in the header of a bitstream// that is used to indicate whether optional features are enabled.FlagsField =iota// Deprecated: HasInit was a bool indicating whether a package// has any init functions.HasInit// Deprecated: DerivedFuncInstance was a bool indicating// whether an object was a function instance.DerivedFuncInstance// ObjAlias has a list of TypeParamNames.AliasTypeParamNames// Deprecated: DerivedInfoNeeded was a bool indicating// whether a type was a derived type.DerivedInfoNeeded)
typeIndex¶
type Indexint32
An Index represents a bitstream element index *within* (i.e., relative to) aparticular section.
typePkgDecoder¶
type PkgDecoder struct {// contains filtered or unexported fields}A PkgDecoder provides methods for decoding a package's Unified IRexport data.
funcNewPkgDecoder¶
func NewPkgDecoder(pkgPath, inputstring)PkgDecoder
NewPkgDecoder returns a PkgDecoder initialized to read the UnifiedIR export data from input. pkgPath is the package path for thecompilation unit that produced the export data.
func (*PkgDecoder)AbsIdx¶
func (pr *PkgDecoder) AbsIdx(kSectionKind, idxRelElemIdx)int
AbsIdx returns the absolute index for the given (section, index)pair.
func (*PkgDecoder)DataIdx¶
func (pr *PkgDecoder) DataIdx(kSectionKind, idxRelElemIdx)string
DataIdx returns the raw element bitstream for the given (section,index) pair.
func (*PkgDecoder)Fingerprint¶
func (pr *PkgDecoder) Fingerprint() [8]byte
Fingerprint returns the package fingerprint.
func (*PkgDecoder)NewDecoder¶
func (pr *PkgDecoder) NewDecoder(kSectionKind, idxRelElemIdx, markerSyncMarker)Decoder
NewDecoder returns a Decoder for the given (section, index) pair,and decodes the given SyncMarker from the element bitstream.
func (*PkgDecoder)NewDecoderRaw¶
func (pr *PkgDecoder) NewDecoderRaw(kSectionKind, idxRelElemIdx)Decoder
NewDecoderRaw returns a Decoder for the given (section, index) pair.
Most callers should use NewDecoder instead.
func (*PkgDecoder)NumElems¶
func (pr *PkgDecoder) NumElems(kSectionKind)int
NumElems returns the number of elements in section k.
func (*PkgDecoder)PeekObj¶
func (pr *PkgDecoder) PeekObj(idxRelElemIdx) (string,string,CodeObj)
PeekObj returns the package path, object name, and CodeObj for thespecified object index.
func (*PkgDecoder)PeekPkgPath¶
func (pr *PkgDecoder) PeekPkgPath(idxRelElemIdx)string
PeekPkgPath returns the package path for the specified packageindex.
func (*PkgDecoder)PkgPath¶
func (pr *PkgDecoder) PkgPath()string
PkgPath returns the package path for the package
TODO(mdempsky): Remove; unneeded since CL 391014.
func (*PkgDecoder)RetireDecoder¶added ingo1.20
func (pr *PkgDecoder) RetireDecoder(d *Decoder)
func (*PkgDecoder)StringIdx¶
func (pr *PkgDecoder) StringIdx(idxRelElemIdx)string
StringIdx returns the string value for the given string index.
func (*PkgDecoder)SyncMarkers¶added ingo1.20
func (pr *PkgDecoder) SyncMarkers()bool
SyncMarkers reports whether pr uses sync markers.
func (*PkgDecoder)TempDecoder¶added ingo1.20
func (pr *PkgDecoder) TempDecoder(kSectionKind, idxRelElemIdx, markerSyncMarker)Decoder
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 longerneeded, this will avoid heap allocations.
func (*PkgDecoder)TempDecoderRaw¶added ingo1.20
func (pr *PkgDecoder) TempDecoderRaw(kSectionKind, idxRelElemIdx)Decoder
func (*PkgDecoder)TotalElems¶
func (pr *PkgDecoder) TotalElems()int
TotalElems returns the total number of elements across all sections.
typePkgEncoder¶
type PkgEncoder struct {// contains filtered or unexported fields}A PkgEncoder provides methods for encoding a package's Unified IRexport data.
funcNewPkgEncoder¶
func NewPkgEncoder(versionVersion, syncFramesint)PkgEncoder
NewPkgEncoder returns an initialized PkgEncoder.
syncFrames is the number of caller frames that should be serializedat Sync points. Serializing additional frames results in largerexport data files, but can help diagnosing desync errors inhigher-level Unified IR reader/writer code. If syncFrames isnegative, then sync markers are omitted entirely.
func (*PkgEncoder)DumpTo¶
func (pw *PkgEncoder) DumpTo(out0io.Writer) (fingerprint [8]byte)
DumpTo writes the package's encoded data to out0 and returns thepackage fingerprint.
func (*PkgEncoder)NewEncoder¶
func (pw *PkgEncoder) NewEncoder(kSectionKind, markerSyncMarker) *Encoder
NewEncoder returns an Encoder for a new element within the givensection, and encodes the given SyncMarker as the start of theelement bitstream.
func (*PkgEncoder)NewEncoderRaw¶
func (pw *PkgEncoder) NewEncoderRaw(kSectionKind) *Encoder
NewEncoderRaw returns an Encoder for a new element within the givensection.
Most callers should use NewEncoder instead.
func (*PkgEncoder)StringIdx¶
func (pw *PkgEncoder) StringIdx(sstring)RelElemIdx
StringIdx adds a string value to the strings section, if notalready present, and returns its index.
func (*PkgEncoder)SyncMarkers¶added ingo1.20
func (pw *PkgEncoder) SyncMarkers()bool
SyncMarkers reports whether pw uses sync markers.
typeRefTableEntry¶added ingo1.25.0
type RefTableEntry struct {KindSectionKindIdxRelElemIdx}A RefTableEntry is an entry in an element's reference table. Allelements are preceded by a reference table which provides locationsfor referenced elements.
typeRelElemIdx¶added ingo1.25.0
type RelElemIdx =Index
TODO(markfreeman): Make this its own type.A RelElemIdx, or relative element index, is an index into the elementsrelative to some other index, such as the start of a section.
const (PublicRootIdxRelElemIdx = 0PrivateRootIdxRelElemIdx = 1)
Reserved indices within theSectionMeta section.
typeSectionKind¶added ingo1.25.0
type SectionKindint32// TODO(markfreeman): Replace with uint8.
A SectionKind indicates a section, as well as the ordering of sections withinunified export data. Any object given a dedicated section can be referred tovia a section / index pair (and thus dereferenced) in other sections.
const (SectionStringSectionKind =iotaSectionMetaSectionPosBaseSectionPkgSectionNameSectionTypeSectionObjSectionObjExtSectionObjDictSectionBody)
typeSyncMarker¶
type SyncMarkerint
SyncMarker is an enum type that represents markers that may bewritten to export data to ensure the reader and writer staysynchronized.
const (// Low-level coding markers.SyncEOF SyncMarkerSyncBoolSyncInt64SyncUint64SyncStringSyncValueSyncValSyncRelocsSyncRelocSyncUseReloc// Higher-level object and type markers.SyncPublicSyncPosSyncPosBaseSyncObjectSyncObject1SyncPkgSyncPkgDefSyncMethodSyncTypeSyncTypeIdxSyncTypeParamNamesSyncSignatureSyncParamsSyncParamSyncCodeObjSyncSymSyncLocalIdentSyncSelector// Private markers (only known to cmd/compile).SyncPrivateSyncFuncExtSyncVarExtSyncTypeExtSyncPragmaSyncExprListSyncExprsSyncExprSyncExprTypeSyncAssignSyncOpSyncFuncLitSyncCompLitSyncDeclSyncFuncBodySyncOpenScopeSyncCloseScopeSyncCloseAnotherScopeSyncDeclNamesSyncDeclNameSyncStmtsSyncBlockStmtSyncIfStmtSyncForStmtSyncSwitchStmtSyncRangeStmtSyncCaseClauseSyncCommClauseSyncSelectStmtSyncDeclsSyncLabeledStmtSyncUseObjLocalSyncAddLocalSyncLinknameSyncStmt1SyncStmtsEndSyncLabelSyncOptLabelSyncMultiExprSyncRTypeSyncConvRTTI)
func (SyncMarker)String¶
func (iSyncMarker) String()string
typeVersion¶added ingo1.24.0
type Versionuint32
Version indicates a version of a unified IR bitstream.Each Version indicates the addition, removal, or change ofnew data in the bitstream.
These are serialized to disk and the interpretation remains fixed.
const (// V0: initial prototype.//// All data that is not assigned a Field is in version V0// and has not been deprecated.V0Version =iota// V1: adds the Flags uint32 wordV1// V2: removes unused legacy fields and supports type parameters for aliases.// - remove the legacy "has init" bool from the public root// - remove obj's "derived func instance" bool// - add a TypeParamNames field to ObjAlias// - remove derived info "needed" boolV2)
Source Files