github.com/shogo82148/std@v1.22.1-0.20240327122250-4e474527810c/internal/pkgbits/encoder.go (about)

     1  // Copyright 2021 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package pkgbits
     6  
     7  import (
     8  	"github.com/shogo82148/std/bytes"
     9  	"github.com/shogo82148/std/go/constant"
    10  	"github.com/shogo82148/std/io"
    11  )
    12  
    13  // A PkgEncoder provides methods for encoding a package's Unified IR
    14  // export data.
    15  type PkgEncoder struct {
    16  	// elems holds the bitstream for previously encoded elements.
    17  	elems [numRelocs][]string
    18  
    19  	// stringsIdx maps previously encoded strings to their index within
    20  	// the RelocString section, to allow deduplication. That is,
    21  	// elems[RelocString][stringsIdx[s]] == s (if present).
    22  	stringsIdx map[string]Index
    23  
    24  	// syncFrames is the number of frames to write at each sync
    25  	// marker. A negative value means sync markers are omitted.
    26  	syncFrames int
    27  }
    28  
    29  // SyncMarkers reports whether pw uses sync markers.
    30  func (pw *PkgEncoder) SyncMarkers() bool
    31  
    32  // NewPkgEncoder returns an initialized PkgEncoder.
    33  //
    34  // syncFrames is the number of caller frames that should be serialized
    35  // at Sync points. Serializing additional frames results in larger
    36  // export data files, but can help diagnosing desync errors in
    37  // higher-level Unified IR reader/writer code. If syncFrames is
    38  // negative, then sync markers are omitted entirely.
    39  func NewPkgEncoder(syncFrames int) PkgEncoder
    40  
    41  // DumpTo writes the package's encoded data to out0 and returns the
    42  // package fingerprint.
    43  func (pw *PkgEncoder) DumpTo(out0 io.Writer) (fingerprint [8]byte)
    44  
    45  // StringIdx adds a string value to the strings section, if not
    46  // already present, and returns its index.
    47  func (pw *PkgEncoder) StringIdx(s string) Index
    48  
    49  // NewEncoder returns an Encoder for a new element within the given
    50  // section, and encodes the given SyncMarker as the start of the
    51  // element bitstream.
    52  func (pw *PkgEncoder) NewEncoder(k RelocKind, marker SyncMarker) Encoder
    53  
    54  // NewEncoderRaw returns an Encoder for a new element within the given
    55  // section.
    56  //
    57  // Most callers should use NewEncoder instead.
    58  func (pw *PkgEncoder) NewEncoderRaw(k RelocKind) Encoder
    59  
    60  // An Encoder provides methods for encoding an individual element's
    61  // bitstream data.
    62  type Encoder struct {
    63  	p *PkgEncoder
    64  
    65  	Relocs   []RelocEnt
    66  	RelocMap map[RelocEnt]uint32
    67  	Data     bytes.Buffer
    68  
    69  	encodingRelocHeader bool
    70  
    71  	k   RelocKind
    72  	Idx Index
    73  }
    74  
    75  // Flush finalizes the element's bitstream and returns its Index.
    76  func (w *Encoder) Flush() Index
    77  
    78  func (w *Encoder) Sync(m SyncMarker)
    79  
    80  // Bool encodes and writes a bool value into the element bitstream,
    81  // and then returns the bool value.
    82  //
    83  // For simple, 2-alternative encodings, the idiomatic way to call Bool
    84  // is something like:
    85  //
    86  //	if w.Bool(x != 0) {
    87  //		// alternative #1
    88  //	} else {
    89  //		// alternative #2
    90  //	}
    91  //
    92  // For multi-alternative encodings, use Code instead.
    93  func (w *Encoder) Bool(b bool) bool
    94  
    95  // Int64 encodes and writes an int64 value into the element bitstream.
    96  func (w *Encoder) Int64(x int64)
    97  
    98  // Uint64 encodes and writes a uint64 value into the element bitstream.
    99  func (w *Encoder) Uint64(x uint64)
   100  
   101  // Len encodes and writes a non-negative int value into the element bitstream.
   102  func (w *Encoder) Len(x int)
   103  
   104  // Int encodes and writes an int value into the element bitstream.
   105  func (w *Encoder) Int(x int)
   106  
   107  // Len encodes and writes a uint value into the element bitstream.
   108  func (w *Encoder) Uint(x uint)
   109  
   110  // Reloc encodes and writes a relocation for the given (section,
   111  // index) pair into the element bitstream.
   112  //
   113  // Note: Only the index is formally written into the element
   114  // bitstream, so bitstream decoders must know from context which
   115  // section an encoded relocation refers to.
   116  func (w *Encoder) Reloc(r RelocKind, idx Index)
   117  
   118  // Code encodes and writes a Code value into the element bitstream.
   119  func (w *Encoder) Code(c Code)
   120  
   121  // String encodes and writes a string value into the element
   122  // bitstream.
   123  //
   124  // Internally, strings are deduplicated by adding them to the strings
   125  // section (if not already present), and then writing a relocation
   126  // into the element bitstream.
   127  func (w *Encoder) String(s string)
   128  
   129  // StringRef writes a reference to the given index, which must be a
   130  // previously encoded string value.
   131  func (w *Encoder) StringRef(idx Index)
   132  
   133  // Strings encodes and writes a variable-length slice of strings into
   134  // the element bitstream.
   135  func (w *Encoder) Strings(ss []string)
   136  
   137  // Value encodes and writes a constant.Value into the element
   138  // bitstream.
   139  func (w *Encoder) Value(val constant.Value)