version.go

     1  // Copyright 2024 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  // Version indicates a version of a unified IR bitstream.
     8  // Each Version indicates the addition, removal, or change of
     9  // new data in the bitstream.
    10  //
    11  // These are serialized to disk and the interpretation remains fixed.
    12  type Version uint32
    13  
    14  const (
    15  	// V0: initial prototype.
    16  	//
    17  	// All data that is not assigned a Field is in version V0
    18  	// and has not been deprecated.
    19  	V0 Version = iota
    20  
    21  	// V1: adds the Flags uint32 word
    22  	V1
    23  
    24  	// V2: removes unused legacy fields and supports type parameters for aliases.
    25  	// - remove the legacy "has init" bool from the public root
    26  	// - remove obj's "derived func instance" bool
    27  	// - add a TypeParamNames field to ObjAlias
    28  	// - remove derived info "needed" bool
    29  	V2
    30  
    31  	// V3: introduces a more compact format for composite literal element lists
    32  	// - negative lengths indicate that (some) elements may have keys
    33  	// - positive lengths indicate that no element has a key
    34  	// - a negative struct field index indicates an embedded field
    35  	V3
    36  
    37  	// V4: encodes generic methods as standalone function objects
    38  	V4
    39  
    40  	// V5: encodes the index of methods to preserve relative order
    41  	// of nongeneric and generic methods (go.dev/issue/81188).
    42  	V5
    43  
    44  	numVersions = iota
    45  )
    46  
    47  // Field denotes a unit of data in the serialized unified IR bitstream.
    48  // It is conceptually a like field in a structure.
    49  //
    50  // We only really need Fields when the data may or may not be present
    51  // in a stream based on the Version of the bitstream.
    52  //
    53  // Unlike much of pkgbits, Fields are not serialized and
    54  // can change values as needed.
    55  type Field int
    56  
    57  const (
    58  	// Flags in a uint32 in the header of a bitstream
    59  	// that is used to indicate whether optional features are enabled.
    60  	Flags Field = iota
    61  
    62  	// Deprecated: HasInit was a bool indicating whether a package
    63  	// has any init functions.
    64  	HasInit
    65  
    66  	// Deprecated: DerivedFuncInstance was a bool indicating
    67  	// whether an object was a function instance.
    68  	DerivedFuncInstance
    69  
    70  	// ObjAlias has a list of TypeParamNames.
    71  	AliasTypeParamNames
    72  
    73  	// Deprecated: DerivedInfoNeeded was a bool indicating
    74  	// whether a type was a derived type.
    75  	DerivedInfoNeeded
    76  
    77  	// Composite literals use a more compact format for element lists.
    78  	CompactCompLiterals
    79  
    80  	// Generic methods may appear as standalone function objects.
    81  	GenericMethods
    82  
    83  	// Method index is encoded to preserve relative order of
    84  	// nongeneric and generic methods.
    85  	PreserveMethodOrder
    86  
    87  	numFields = iota
    88  )
    89  
    90  // introduced is the version a field was added.
    91  var introduced = [numFields]Version{
    92  	Flags:               V1,
    93  	AliasTypeParamNames: V2,
    94  	CompactCompLiterals: V3,
    95  	GenericMethods:      V4,
    96  	PreserveMethodOrder: V5,
    97  }
    98  
    99  // removed is the version a field was removed in or 0 for fields
   100  // that have not yet been deprecated.
   101  // (So removed[f]-1 is the last version it is included in.)
   102  var removed = [numFields]Version{
   103  	HasInit:             V2,
   104  	DerivedFuncInstance: V2,
   105  	DerivedInfoNeeded:   V2,
   106  }
   107  
   108  // Has reports whether field f is present in a bitstream at version v.
   109  func (v Version) Has(f Field) bool {
   110  	return introduced[f] <= v && (v < removed[f] || removed[f] == V0)
   111  }
   112
View as plain text