internal/pkgbits: specify that RelIdx is an element index

Without this, it's not clear what this is relative to or the
granularity of the index.

Change-Id: Ibaabe47e089f0ba9b084523969c5347ed4c9dbee
Reviewed-on: https://go-review.googlesource.com/c/go/+/674636
Auto-Submit: Mark Freeman <mark@golang.org>
Reviewed-by: Robert Griesemer <gri@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

Author: Mark Freeman

src/internal/pkgbits/decoder.go

@@ -131,7 +131,7 @@ func (pr *PkgDecoder) Fingerprint() [8]byte {
 
 // AbsIdx returns the absolute index for the given (section, index)
 // pair.
-func (pr *PkgDecoder) AbsIdx(k SectionKind, idx RelIndex) int {
+func (pr *PkgDecoder) AbsIdx(k SectionKind, idx RelElemIdx) int {
 	absIdx := int(idx)
 	if k > 0 {
 		absIdx += int(pr.elemEndsEnds[k-1])
@@ -144,7 +144,7 @@ func (pr *PkgDecoder) AbsIdx(k SectionKind, idx RelIndex) int {
 
 // DataIdx returns the raw element bitstream for the given (section,
 // index) pair.
-func (pr *PkgDecoder) DataIdx(k SectionKind, idx RelIndex) string {
+func (pr *PkgDecoder) DataIdx(k SectionKind, idx RelElemIdx) string {
 	absIdx := pr.AbsIdx(k, idx)
 
 	var start uint32
@@ -157,13 +157,13 @@ func (pr *PkgDecoder) DataIdx(k SectionKind, idx RelIndex) string {
 }
 
 // StringIdx returns the string value for the given string index.
-func (pr *PkgDecoder) StringIdx(idx RelIndex) string {
+func (pr *PkgDecoder) StringIdx(idx RelElemIdx) string {
 	return pr.DataIdx(SectionString, idx)
 }
 
 // NewDecoder returns a Decoder for the given (section, index) pair,
 // and decodes the given SyncMarker from the element bitstream.
-func (pr *PkgDecoder) NewDecoder(k SectionKind, idx RelIndex, marker SyncMarker) Decoder {
+func (pr *PkgDecoder) NewDecoder(k SectionKind, idx RelElemIdx, marker SyncMarker) Decoder {
 	r := pr.NewDecoderRaw(k, idx)
 	r.Sync(marker)
 	return r
@@ -173,7 +173,7 @@ func (pr *PkgDecoder) NewDecoder(k SectionKind, idx RelIndex, marker SyncMarker)
 // 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.
-func (pr *PkgDecoder) TempDecoder(k SectionKind, idx RelIndex, marker SyncMarker) Decoder {
+func (pr *PkgDecoder) TempDecoder(k SectionKind, idx RelElemIdx, marker SyncMarker) Decoder {
 	r := pr.TempDecoderRaw(k, idx)
 	r.Sync(marker)
 	return r
@@ -187,7 +187,7 @@ func (pr *PkgDecoder) RetireDecoder(d *Decoder) {
 // NewDecoderRaw returns a Decoder for the given (section, index) pair.
 //
 // Most callers should use NewDecoder instead.
-func (pr *PkgDecoder) NewDecoderRaw(k SectionKind, idx RelIndex) Decoder {
+func (pr *PkgDecoder) NewDecoderRaw(k SectionKind, idx RelElemIdx) Decoder {
 	r := Decoder{
 		common: pr,
 		k:      k,
@@ -199,13 +199,13 @@ func (pr *PkgDecoder) NewDecoderRaw(k SectionKind, idx RelIndex) Decoder {
 	r.Relocs = make([]RefTableEntry, r.Len())
 	for i := range r.Relocs {
 		r.Sync(SyncReloc)
-		r.Relocs[i] = RefTableEntry{SectionKind(r.Len()), RelIndex(r.Len())}
+		r.Relocs[i] = RefTableEntry{SectionKind(r.Len()), RelElemIdx(r.Len())}
 	}
 
 	return r
 }
 
-func (pr *PkgDecoder) TempDecoderRaw(k SectionKind, idx RelIndex) Decoder {
+func (pr *PkgDecoder) TempDecoderRaw(k SectionKind, idx RelElemIdx) Decoder {
 	r := Decoder{
 		common: pr,
 		k:      k,
@@ -223,7 +223,7 @@ func (pr *PkgDecoder) TempDecoderRaw(k SectionKind, idx RelIndex) Decoder {
 	}
 	for i := range r.Relocs {
 		r.Sync(SyncReloc)
-		r.Relocs[i] = RefTableEntry{SectionKind(r.Len()), RelIndex(r.Len())}
+		r.Relocs[i] = RefTableEntry{SectionKind(r.Len()), RelElemIdx(r.Len())}
 	}
 
 	return r
@@ -238,7 +238,7 @@ type Decoder struct {
 	Data   strings.Reader
 
 	k   SectionKind
-	Idx RelIndex
+	Idx RelElemIdx
 }
 
 func (r *Decoder) checkErr(err error) {
@@ -292,7 +292,7 @@ func (r *Decoder) rawVarint() int64 {
 	return x
 }
 
-func (r *Decoder) rawReloc(k SectionKind, idx int) RelIndex {
+func (r *Decoder) rawReloc(k SectionKind, idx int) RelElemIdx {
 	e := r.Relocs[idx]
 	assert(e.Kind == k)
 	return e.Idx
@@ -401,7 +401,7 @@ func (r *Decoder) Code(mark SyncMarker) int {
 
 // Reloc decodes a relocation of expected section k from the element
 // bitstream and returns an index to the referenced element.
-func (r *Decoder) Reloc(k SectionKind) RelIndex {
+func (r *Decoder) Reloc(k SectionKind) RelElemIdx {
 	r.Sync(SyncUseReloc)
 	return r.rawReloc(k, r.Len())
 }
@@ -478,7 +478,7 @@ func (r *Decoder) bigFloat() *big.Float {
 
 // PeekPkgPath returns the package path for the specified package
 // index.
-func (pr *PkgDecoder) PeekPkgPath(idx RelIndex) string {
+func (pr *PkgDecoder) PeekPkgPath(idx RelElemIdx) string {
 	var path string
 	{
 		r := pr.TempDecoder(SectionPkg, idx, SyncPkgDef)
@@ -493,8 +493,8 @@ func (pr *PkgDecoder) PeekPkgPath(idx RelIndex) string {
 
 // PeekObj returns the package path, object name, and CodeObj for the
 // specified object index.
-func (pr *PkgDecoder) PeekObj(idx RelIndex) (string, string, CodeObj) {
-	var ridx RelIndex
+func (pr *PkgDecoder) PeekObj(idx RelElemIdx) (string, string, CodeObj) {
+	var ridx RelElemIdx
 	var name string
 	var rcode int
 	{

src/internal/pkgbits/encoder.go

@@ -27,7 +27,7 @@ type PkgEncoder struct {
 	// stringsIdx maps previously encoded strings to their index within
 	// the RelocString section, to allow deduplication. That is,
 	// elems[RelocString][stringsIdx[s]] == s (if present).
-	stringsIdx map[string]RelIndex
+	stringsIdx map[string]RelElemIdx
 
 	// syncFrames is the number of frames to write at each sync
 	// marker. A negative value means sync markers are omitted.
@@ -47,7 +47,7 @@ func (pw *PkgEncoder) SyncMarkers() bool { return pw.syncFrames >= 0 }
 func NewPkgEncoder(version Version, syncFrames int) PkgEncoder {
 	return PkgEncoder{
 		version:    version,
-		stringsIdx: make(map[string]RelIndex),
+		stringsIdx: make(map[string]RelElemIdx),
 		syncFrames: syncFrames,
 	}
 }
@@ -106,13 +106,13 @@ func (pw *PkgEncoder) DumpTo(out0 io.Writer) (fingerprint [8]byte) {
 
 // StringIdx adds a string value to the strings section, if not
 // already present, and returns its index.
-func (pw *PkgEncoder) StringIdx(s string) RelIndex {
+func (pw *PkgEncoder) StringIdx(s string) RelElemIdx {
 	if idx, ok := pw.stringsIdx[s]; ok {
 		assert(pw.elems[SectionString][idx] == s)
 		return idx
 	}
 
-	idx := RelIndex(len(pw.elems[SectionString]))
+	idx := RelElemIdx(len(pw.elems[SectionString]))
 	pw.elems[SectionString] = append(pw.elems[SectionString], s)
 	pw.stringsIdx[s] = idx
 	return idx
@@ -132,7 +132,7 @@ func (pw *PkgEncoder) NewEncoder(k SectionKind, marker SyncMarker) *Encoder {
 //
 // Most callers should use NewEncoder instead.
 func (pw *PkgEncoder) NewEncoderRaw(k SectionKind) *Encoder {
-	idx := RelIndex(len(pw.elems[k]))
+	idx := RelElemIdx(len(pw.elems[k]))
 	pw.elems[k] = append(pw.elems[k], "") // placeholder
 
 	return &Encoder{
@@ -154,11 +154,11 @@ type Encoder struct {
 	encodingRelocHeader bool
 
 	k   SectionKind
-	Idx RelIndex // index within relocation section
+	Idx RelElemIdx // index within relocation section
 }
 
-// Flush finalizes the element's bitstream and returns its [RelIndex].
-func (w *Encoder) Flush() RelIndex {
+// Flush finalizes the element's bitstream and returns its [RelElemIdx].
+func (w *Encoder) Flush() RelElemIdx {
 	var sb strings.Builder
 
 	// Backup the data so we write the relocations at the front.
@@ -210,7 +210,7 @@ func (w *Encoder) rawVarint(x int64) {
 	w.rawUvarint(ux)
 }
 
-func (w *Encoder) rawReloc(k SectionKind, idx RelIndex) int {
+func (w *Encoder) rawReloc(k SectionKind, idx RelElemIdx) int {
 	e := RefTableEntry{k, idx}
 	if w.RelocMap != nil {
 		if i, ok := w.RelocMap[e]; ok {
@@ -302,7 +302,7 @@ func (w *Encoder) Uint(x uint) { w.Uint64(uint64(x)) }
 // 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.
-func (w *Encoder) Reloc(k SectionKind, idx RelIndex) {
+func (w *Encoder) Reloc(k SectionKind, idx RelElemIdx) {
 	w.Sync(SyncUseReloc)
 	w.Len(w.rawReloc(k, idx))
 }
@@ -325,7 +325,7 @@ func (w *Encoder) String(s string) {
 
 // StringRef writes a reference to the given index, which must be a
 // previously encoded string value.
-func (w *Encoder) StringRef(idx RelIndex) {
+func (w *Encoder) StringRef(idx RelElemIdx) {
 	w.Sync(SyncString)
 	w.Reloc(SectionString, idx)
 }

src/internal/pkgbits/reloc.go

@@ -28,20 +28,26 @@ const (
 // particular section.
 type Index int32
 
-// TODO(markfreeman): Make RelIndex its own named type once we point external
-// references from Index to RelIndex.
-type RelIndex = Index
+// An AbsElemIdx, or absolute element index, is an index into the elements
+// that is not relative to some other index.
+type AbsElemIdx = uint32
 
+// TODO(markfreeman): Make this its own type.
+// A RelElemIdx, or relative element index, is an index into the elements
+// relative to some other index, such as the start of a section.
+type RelElemIdx = Index
+
+// TODO(markfreeman): Isn't this strictly less efficient than an AbsElemIdx?
 // A RefTableEntry is an entry in an element's reference table. All
 // elements are preceded by a reference table which provides locations
 // for referenced elements.
 type RefTableEntry struct {
 	Kind SectionKind
-	Idx  RelIndex
+	Idx  RelElemIdx
 }
 
 // Reserved indices within the [SectionMeta] section.
 const (
-	PublicRootIdx  RelIndex = 0
-	PrivateRootIdx RelIndex = 1
+	PublicRootIdx  RelElemIdx = 0
+	PrivateRootIdx RelElemIdx = 1
 )