golang.org/x/exp@v0.0.0-20240506185415-9bf2ced13842/trace/internal/event/event.go (about)

     1  // Copyright 2023 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  // Code generated by "gen.bash" from internal/trace/v2; DO NOT EDIT.
     6  
     7  //go:build go1.21
     8  
     9  package event
    10  
    11  // Type is the common in-memory representation of the low-leve
    12  type Type uint8
    13  
    14  // Spec is a specification for a trace event. It contains sufficient information
    15  // to perform basic parsing of any trace event for any version of Go.
    16  type Spec struct {
    17  	// Name is the human-readable name of the trace event.
    18  	Name string
    19  
    20  	// Args contains the names of each trace event's argument.
    21  	// Its length determines the number of arguments an event has.
    22  	//
    23  	// Argument names follow a certain structure and this structure
    24  	// is relied on by the testing framework to type-check arguments.
    25  	// The structure is is:
    26  	//
    27  	//     (?P<name>[A-Za-z]+_)?(?P<type>[A-Za-z]+)
    28  	//
    29  	// In sum, it's an optional name followed by a type. If the name
    30  	// is present, it is separated from the type with an underscore.
    31  	// The valid argument types and the Go types they map to are listed
    32  	// in the ArgTypes variable.
    33  	Args []string
    34  
    35  	// StartEv indicates the event type of the corresponding "start"
    36  	// event, if this event is an "end," for a pair of events that
    37  	// represent a time range.
    38  	StartEv Type
    39  
    40  	// IsTimedEvent indicates whether this is an event that both
    41  	// appears in the main event stream and is surfaced to the
    42  	// trace reader.
    43  	//
    44  	// Events that are not "timed" are considered "structural"
    45  	// since they either need significant reinterpretation or
    46  	// otherwise aren't actually surfaced by the trace reader.
    47  	IsTimedEvent bool
    48  
    49  	// HasData is true if the event has trailer consisting of a
    50  	// varint length followed by unencoded bytes of some data.
    51  	HasData bool
    52  
    53  	// StringIDs indicates which of the arguments are string IDs.
    54  	StringIDs []int
    55  
    56  	// StackIDs indicates which of the arguments are stack IDs.
    57  	//
    58  	// The list is not sorted. The first index always refers to
    59  	// the main stack for the current execution context of the event.
    60  	StackIDs []int
    61  
    62  	// IsStack indicates that the event represents a complete
    63  	// stack trace. Specifically, it means that after the arguments
    64  	// there's a varint length, followed by 4*length varints. Each
    65  	// group of 4 represents the PC, file ID, func ID, and line number
    66  	// in that order.
    67  	IsStack bool
    68  }
    69  
    70  // ArgTypes is a list of valid argument types for use in Args.
    71  //
    72  // See the documentation of Args for more details.
    73  var ArgTypes = [...]string{
    74  	"seq",     // sequence number
    75  	"pstatus", // P status
    76  	"gstatus", // G status
    77  	"g",       // trace.GoID
    78  	"m",       // trace.ThreadID
    79  	"p",       // trace.ProcID
    80  	"string",  // string ID
    81  	"stack",   // stack ID
    82  	"value",   // uint64
    83  	"task",    // trace.TaskID
    84  }
    85  
    86  // Names is a helper that produces a mapping of event names to event types.
    87  func Names(specs []Spec) map[string]Type {
    88  	nameToType := make(map[string]Type)
    89  	for i, spec := range specs {
    90  		nameToType[spec.Name] = Type(byte(i))
    91  	}
    92  	return nameToType
    93  }