package pkgbits

Import Path
	internal/pkgbits (on go.dev)

Dependency Relation
	imports 13 packages, and imported by one package

Involved Source Files

	    codes.go
	    decoder.go
	  d doc.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).

	    encoder.go
	    flags.go
	    reloc.go
	    support.go
	    sync.go
	    syncmarker_string.go
Package-Level Type Names (total 12)

	/* sort by: alphabet | popularity */
	 type Code (interface)
		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.

		Methods (total 2)
			( Code) Marker() SyncMarker
				Marker returns the SyncMarker for the Code's dynamic type.

			( Code) Value() int
				Value returns the Code's ordinal value.

		Implemented By (at least 3)
			 CodeObj
			 CodeType
			 CodeVal
		As Inputs Of (at least one exported)
			func (*Encoder).Code(c Code)

	 type CodeObj int (basic type)
		A CodeObj distinguishes among go/types.Object encodings.

		Methods (total 2)
			( CodeObj) Marker() SyncMarker
			( CodeObj) Value() int
		Implements (at least one exported)
			 CodeObj : Code
		As Outputs Of (at least one exported)
			func (*PkgDecoder).PeekObj(idx Index) (string, string, CodeObj)
		As Types Of (total 6)
			const ObjAlias
			const ObjConst
			const ObjFunc
			const ObjStub
			const ObjType
			const ObjVar

	 type CodeType int (basic type)
		A CodeType distinguishes among go/types.Type encodings.

		Methods (total 2)
			( CodeType) Marker() SyncMarker
			( CodeType) Value() int
		Implements (at least one exported)
			 CodeType : Code
		As Types Of (total 12)
			const TypeArray
			const TypeBasic
			const TypeChan
			const TypeInterface
			const TypeMap
			const TypeNamed
			const TypePointer
			const TypeSignature
			const TypeSlice
			const TypeStruct
			const TypeTypeParam
			const TypeUnion

	 type CodeVal int (basic type)
		A CodeVal distinguishes among go/constant.Value encodings.

		Methods (total 2)
			( CodeVal) Marker() SyncMarker
			( CodeVal) Value() int
		Implements (at least one exported)
			 CodeVal : Code
		As Types Of (total 6)
			const ValBigFloat
			const ValBigInt
			const ValBigRat
			const ValBool
			const ValInt64
			const ValString

	 type Decoder (struct)
		A Decoder provides methods for decoding an individual element's
		bitstream data.

		Fields (total 3)
			Data strings.Reader
			Idx Index
			Relocs []RelocEnt
		Methods (total 12)
			(*Decoder) Bool() bool
				Bool decodes and returns a bool value from the element bitstream.

			(*Decoder) Code(mark SyncMarker) int
				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.

			(*Decoder) Int() int
				Int decodes and returns an int value from the element bitstream.

			(*Decoder) Int64() int64
				Int64 decodes and returns an int64 value from the element bitstream.

			(*Decoder) Len() int
				Len decodes and returns a non-negative int value from the element bitstream.

			(*Decoder) Reloc(k RelocKind) Index
				Reloc decodes a relocation of expected section k from the element
				bitstream and returns an index to the referenced element.

			(*Decoder) String() string
				String decodes and returns a string value from the element
				bitstream.

			(*Decoder) Strings() []string
				Strings decodes and returns a variable-length slice of strings from
				the element bitstream.

			(*Decoder) Sync(mWant SyncMarker)
				Sync decodes a sync marker from the element bitstream and asserts
				that it matches the expected marker.
				
				If EnableSync is false, then Sync is a no-op.

			(*Decoder) Uint() uint
				Uint decodes and returns a uint value from the element bitstream.

			(*Decoder) Uint64() uint64
				Int64 decodes and returns a uint64 value from the element bitstream.

			(*Decoder) Value() constant.Value
				Value decodes and returns a constant.Value from the element
				bitstream.

		Implements (at least 3)
			*Decoder : expvar.Var
			*Decoder : fmt.Stringer
			*Decoder : math/rand/v2.Source
		As Outputs Of (at least 4)
			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
		As Inputs Of (at least one exported)
			func (*PkgDecoder).RetireDecoder(d *Decoder)

	 type Encoder (struct)
		An Encoder provides methods for encoding an individual element's
		bitstream data.

		Fields (total 4)
			Data bytes.Buffer
				// accumulated element bitstream data

			Idx Index
				// index within relocation section

			RelocMap map[RelocEnt]uint32
			Relocs []RelocEnt
		Methods (total 14)
			(*Encoder) Bool(b bool) 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 Bool
				is something like:
				
					if w.Bool(x != 0) {
						// alternative #1
					} else {
						// alternative #2
					}
				
				For multi-alternative encodings, use Code instead.

			(*Encoder) Code(c Code)
				Code encodes and writes a Code value into the element bitstream.

			(*Encoder) Flush() Index
				Flush finalizes the element's bitstream and returns its Index.

			(*Encoder) Int(x int)
				Int encodes and writes an int value into the element bitstream.

			(*Encoder) Int64(x int64)
				Int64 encodes and writes an int64 value into the element bitstream.

			(*Encoder) Len(x int)
				Len encodes and writes a non-negative int value into the element bitstream.

			(*Encoder) Reloc(r RelocKind, idx Index)
				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.

			(*Encoder) String(s string)
				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.

			(*Encoder) StringRef(idx Index)
				StringRef writes a reference to the given index, which must be a
				previously encoded string value.

			(*Encoder) Strings(ss []string)
				Strings encodes and writes a variable-length slice of strings into
				the element bitstream.

			(*Encoder) Sync(m SyncMarker)
			(*Encoder) Uint(x uint)
				Len encodes and writes a uint value into the element bitstream.

			(*Encoder) Uint64(x uint64)
				Uint64 encodes and writes a uint64 value into the element bitstream.

			(*Encoder) Value(val constant.Value)
				Value encodes and writes a constant.Value into the element
				bitstream.

		As Outputs Of (at least 2)
			func (*PkgEncoder).NewEncoder(k RelocKind, marker SyncMarker) Encoder
			func (*PkgEncoder).NewEncoderRaw(k RelocKind) Encoder

	 type Index int32 (basic type)
		An Index represents a bitstream element index within a particular
		section.

		As Outputs Of (at least 3)
			func (*Decoder).Reloc(k RelocKind) Index
			func (*Encoder).Flush() Index
			func (*PkgEncoder).StringIdx(s string) Index
		As Inputs Of (at least 11)
			func (*Encoder).Reloc(r RelocKind, idx Index)
			func (*Encoder).StringRef(idx Index)
			func (*PkgDecoder).AbsIdx(k RelocKind, idx Index) int
			func (*PkgDecoder).DataIdx(k RelocKind, idx Index) string
			func (*PkgDecoder).NewDecoder(k RelocKind, idx Index, marker SyncMarker) Decoder
			func (*PkgDecoder).NewDecoderRaw(k RelocKind, idx Index) Decoder
			func (*PkgDecoder).PeekObj(idx Index) (string, string, CodeObj)
			func (*PkgDecoder).PeekPkgPath(idx Index) string
			func (*PkgDecoder).StringIdx(idx Index) string
			func (*PkgDecoder).TempDecoder(k RelocKind, idx Index, marker SyncMarker) Decoder
			func (*PkgDecoder).TempDecoderRaw(k RelocKind, idx Index) Decoder
		As Types Of (total 2)
			const PrivateRootIdx
			const PublicRootIdx

	 type PkgDecoder (struct)
		A PkgDecoder provides methods for decoding a package's Unified IR
		export data.

		Methods (total 15)
			(*PkgDecoder) AbsIdx(k RelocKind, idx Index) int
				AbsIdx returns the absolute index for the given (section, index)
				pair.

			(*PkgDecoder) DataIdx(k RelocKind, idx Index) string
				DataIdx returns the raw element bitstream for the given (section,
				index) pair.

			(*PkgDecoder) Fingerprint() [8]byte
				Fingerprint returns the package fingerprint.

			(*PkgDecoder) NewDecoder(k RelocKind, idx Index, marker SyncMarker) Decoder
				NewDecoder returns a Decoder for the given (section, index) pair,
				and decodes the given SyncMarker from the element bitstream.

			(*PkgDecoder) NewDecoderRaw(k RelocKind, idx Index) Decoder
				NewDecoderRaw returns a Decoder for the given (section, index) pair.
				
				Most callers should use NewDecoder instead.

			(*PkgDecoder) NumElems(k RelocKind) int
				NumElems returns the number of elements in section k.

			(*PkgDecoder) PeekObj(idx Index) (string, string, CodeObj)
				PeekObj returns the package path, object name, and CodeObj for the
				specified object index.

			(*PkgDecoder) PeekPkgPath(idx Index) string
				PeekPkgPath returns the package path for the specified package
				index.

			(*PkgDecoder) PkgPath() string
				PkgPath returns the package path for the package
				
				TODO(mdempsky): Remove; unneeded since CL 391014.

			(*PkgDecoder) RetireDecoder(d *Decoder)
			(*PkgDecoder) StringIdx(idx Index) string
				StringIdx returns the string value for the given string index.

			(*PkgDecoder) SyncMarkers() bool
				SyncMarkers reports whether pr uses sync markers.

			(*PkgDecoder) TempDecoder(k RelocKind, idx Index, marker SyncMarker) 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 longer
				needed, this will avoid heap allocations.

			(*PkgDecoder) TempDecoderRaw(k RelocKind, idx Index) Decoder
			(*PkgDecoder) TotalElems() int
				TotalElems returns the total number of elements across all sections.

		As Outputs Of (at least one exported)
			func NewPkgDecoder(pkgPath, input string) PkgDecoder

	 type PkgEncoder (struct)
		A PkgEncoder provides methods for encoding a package's Unified IR
		export data.

		Methods (total 5)
			(*PkgEncoder) DumpTo(out0 io.Writer) (fingerprint [8]byte)
				DumpTo writes the package's encoded data to out0 and returns the
				package fingerprint.

			(*PkgEncoder) NewEncoder(k RelocKind, marker SyncMarker) Encoder
				NewEncoder returns an Encoder for a new element within the given
				section, and encodes the given SyncMarker as the start of the
				element bitstream.

			(*PkgEncoder) NewEncoderRaw(k RelocKind) Encoder
				NewEncoderRaw returns an Encoder for a new element within the given
				section.
				
				Most callers should use NewEncoder instead.

			(*PkgEncoder) StringIdx(s string) Index
				StringIdx adds a string value to the strings section, if not
				already present, and returns its index.

			(*PkgEncoder) SyncMarkers() bool
				SyncMarkers reports whether pw uses sync markers.

		As Outputs Of (at least one exported)
			func NewPkgEncoder(syncFrames int) PkgEncoder

	 type RelocEnt (struct)
		A relocEnt (relocation entry) is an entry in an element's local
		reference table.
		
		TODO(mdempsky): Rename this too.

		Fields (total 2)
			Idx Index
			Kind RelocKind

	 type RelocKind int32 (basic type)
		A RelocKind indicates a particular section within a unified IR export.

		As Inputs Of (at least 11)
			func (*Decoder).Reloc(k RelocKind) Index
			func (*Encoder).Reloc(r RelocKind, idx Index)
			func (*PkgDecoder).AbsIdx(k RelocKind, idx Index) int
			func (*PkgDecoder).DataIdx(k RelocKind, idx Index) string
			func (*PkgDecoder).NewDecoder(k RelocKind, idx Index, marker SyncMarker) Decoder
			func (*PkgDecoder).NewDecoderRaw(k RelocKind, idx Index) Decoder
			func (*PkgDecoder).NumElems(k RelocKind) int
			func (*PkgDecoder).TempDecoder(k RelocKind, idx Index, marker SyncMarker) Decoder
			func (*PkgDecoder).TempDecoderRaw(k RelocKind, idx Index) Decoder
			func (*PkgEncoder).NewEncoder(k RelocKind, marker SyncMarker) Encoder
			func (*PkgEncoder).NewEncoderRaw(k RelocKind) Encoder
		As Types Of (total 10)
			const RelocBody
			const RelocMeta
			const RelocName
			const RelocObj
			const RelocObjDict
			const RelocObjExt
			const RelocPkg
			const RelocPosBase
			const RelocString
			const RelocType

	 type SyncMarker int (basic type)
		SyncMarker is an enum type that represents markers that may be
		written to export data to ensure the reader and writer stay
		synchronized.

		Methods (only one)
			( SyncMarker) String() string
		Implements (at least 2)
			 SyncMarker : expvar.Var
			 SyncMarker : fmt.Stringer
		As Outputs Of (at least 4)
			func Code.Marker() SyncMarker
			func CodeObj.Marker() SyncMarker
			func CodeType.Marker() SyncMarker
			func CodeVal.Marker() SyncMarker
		As Inputs Of (at least 6)
			func (*Decoder).Code(mark SyncMarker) int
			func (*Decoder).Sync(mWant SyncMarker)
			func (*Encoder).Sync(m SyncMarker)
			func (*PkgDecoder).NewDecoder(k RelocKind, idx Index, marker SyncMarker) Decoder
			func (*PkgDecoder).TempDecoder(k RelocKind, idx Index, marker SyncMarker) Decoder
			func (*PkgEncoder).NewEncoder(k RelocKind, marker SyncMarker) Encoder
		As Types Of (total 69)
			const SyncAddLocal
			const SyncAssign
			const SyncBlockStmt
			const SyncBool
			const SyncCaseClause
			const SyncCloseAnotherScope
			const SyncCloseScope
			const SyncCodeObj
			const SyncCommClause
			const SyncCompLit
			const SyncConvRTTI
			const SyncDecl
			const SyncDeclName
			const SyncDeclNames
			const SyncDecls
			const SyncEOF
			const SyncExpr
			const SyncExprList
			const SyncExprs
			const SyncExprType
			const SyncForStmt
			const SyncFuncBody
			const SyncFuncExt
			const SyncFuncLit
			const SyncIfStmt
			const SyncInt64
			const SyncLabel
			const SyncLabeledStmt
			const SyncLinkname
			const SyncLocalIdent
			const SyncMethod
			const SyncMultiExpr
			const SyncObject
			const SyncObject1
			const SyncOp
			const SyncOpenScope
			const SyncOptLabel
			const SyncParam
			const SyncParams
			const SyncPkg
			const SyncPkgDef
			const SyncPos
			const SyncPosBase
			const SyncPragma
			const SyncPrivate
			const SyncPublic
			const SyncRangeStmt
			const SyncReloc
			const SyncRelocs
			const SyncRType
			const SyncSelector
			const SyncSelectStmt
			const SyncSignature
			const SyncStmt1
			const SyncStmts
			const SyncStmtsEnd
			const SyncString
			const SyncSwitchStmt
			const SyncSym
			const SyncType
			const SyncTypeExt
			const SyncTypeIdx
			const SyncTypeParamNames
			const SyncUint64
			const SyncUseObjLocal
			const SyncUseReloc
			const SyncVal
			const SyncValue
			const SyncVarExt


Package-Level Functions (total 2)

	 func NewPkgDecoder(pkgPath, input string) PkgDecoder
		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.

	 func NewPkgEncoder(syncFrames int) PkgEncoder
		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.


Package-Level Constants (total 105)

	const ObjAlias CodeObj = 0
	const ObjConst CodeObj = 1
	const ObjFunc CodeObj = 3
	const ObjStub CodeObj = 5
	const ObjType CodeObj = 2
	const ObjVar CodeObj = 4
	const PrivateRootIdx Index = 1
		Reserved indices within the meta relocation section.

	const PublicRootIdx Index = 0
		Reserved indices within the meta relocation section.

	const RelocBody RelocKind = 9
	const RelocMeta RelocKind = 1
	const RelocName RelocKind = 4
	const RelocObj RelocKind = 6
	const RelocObjDict RelocKind = 8
	const RelocObjExt RelocKind = 7
	const RelocPkg RelocKind = 3
	const RelocPosBase RelocKind = 2
	const RelocString RelocKind = 0
	const RelocType RelocKind = 5
	const SyncAddLocal SyncMarker = 61
	const SyncAssign SyncMarker = 38
	const SyncBlockStmt SyncMarker = 50
	const SyncBool SyncMarker = 2
	const SyncCaseClause SyncMarker = 55
	const SyncCloseAnotherScope SyncMarker = 46
	const SyncCloseScope SyncMarker = 45
	const SyncCodeObj SyncMarker = 25
	const SyncCommClause SyncMarker = 56
	const SyncCompLit SyncMarker = 41
	const SyncConvRTTI SyncMarker = 69
	const SyncDecl SyncMarker = 42
	const SyncDeclName SyncMarker = 48
	const SyncDeclNames SyncMarker = 47
	const SyncDecls SyncMarker = 58
	const SyncEOF SyncMarker = 1
		Low-level coding markers.

	const SyncExpr SyncMarker = 36
	const SyncExprList SyncMarker = 34
	const SyncExprs SyncMarker = 35
	const SyncExprType SyncMarker = 37
	const SyncForStmt SyncMarker = 52
	const SyncFuncBody SyncMarker = 43
	const SyncFuncExt SyncMarker = 30
	const SyncFuncLit SyncMarker = 40
	const SyncIfStmt SyncMarker = 51
	const SyncInt64 SyncMarker = 3
	const SyncLabel SyncMarker = 65
	const SyncLabeledStmt SyncMarker = 59
	const SyncLinkname SyncMarker = 62
	const SyncLocalIdent SyncMarker = 27
	const SyncMethod SyncMarker = 18
	const SyncMultiExpr SyncMarker = 67
	const SyncObject SyncMarker = 14
	const SyncObject1 SyncMarker = 15
	const SyncOp SyncMarker = 39
	const SyncOpenScope SyncMarker = 44
	const SyncOptLabel SyncMarker = 66
	const SyncParam SyncMarker = 24
	const SyncParams SyncMarker = 23
	const SyncPkg SyncMarker = 16
	const SyncPkgDef SyncMarker = 17
	const SyncPos SyncMarker = 12
	const SyncPosBase SyncMarker = 13
	const SyncPragma SyncMarker = 33
	const SyncPrivate SyncMarker = 29
		Private markers (only known to cmd/compile).

	const SyncPublic SyncMarker = 11
		Higher-level object and type markers.

	const SyncRangeStmt SyncMarker = 54
	const SyncReloc SyncMarker = 9
	const SyncRelocs SyncMarker = 8
	const SyncRType SyncMarker = 68
	const SyncSelector SyncMarker = 28
	const SyncSelectStmt SyncMarker = 57
	const SyncSignature SyncMarker = 22
	const SyncStmt1 SyncMarker = 63
	const SyncStmts SyncMarker = 49
	const SyncStmtsEnd SyncMarker = 64
	const SyncString SyncMarker = 5
	const SyncSwitchStmt SyncMarker = 53
	const SyncSym SyncMarker = 26
	const SyncType SyncMarker = 19
	const SyncTypeExt SyncMarker = 32
	const SyncTypeIdx SyncMarker = 20
	const SyncTypeParamNames SyncMarker = 21
	const SyncUint64 SyncMarker = 4
	const SyncUseObjLocal SyncMarker = 60
	const SyncUseReloc SyncMarker = 10
	const SyncVal SyncMarker = 7
	const SyncValue SyncMarker = 6
	const SyncVarExt SyncMarker = 31
	const TypeArray CodeType = 4
	const TypeBasic CodeType = 0
	const TypeChan CodeType = 5
	const TypeInterface CodeType = 9
	const TypeMap CodeType = 6
	const TypeNamed CodeType = 1
	const TypePointer CodeType = 2
	const TypeSignature CodeType = 7
	const TypeSlice CodeType = 3
	const TypeStruct CodeType = 8
	const TypeTypeParam CodeType = 11
	const TypeUnion CodeType = 10
	const ValBigFloat CodeVal = 5
	const ValBigInt CodeVal = 3
	const ValBigRat CodeVal = 4
	const ValBool CodeVal = 0
	const ValInt64 CodeVal = 2
	const ValString CodeVal = 1

The pages are generated with Golds v0.7.0-preview. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.