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