LLDB mainline
SBTraceCursor.h
Go to the documentation of this file.
1//===-- SBTraceCursor.h -----------------------------------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#ifndef LLDB_API_SBTRACECURSOR_H
10#define LLDB_API_SBTRACECURSOR_H
11
12#include "lldb/API/SBDefines.h"
13#include "lldb/API/SBError.h"
15
16namespace lldb {
17
19public:
20 /// Default constructor for an invalid \a SBTraceCursor object.
22
23 /// Create a cursor that initially points to the end of the trace, i.e. the
24 /// most recent item.
25 SBTraceCursor(lldb::TraceCursorSP trace_cursor_sp);
26
27 /// Set the direction to use in the \a SBTraceCursor::Next() method.
28 ///
29 /// \param[in] forwards
30 /// If \b true, then the traversal will be forwards, otherwise backwards.
31 void SetForwards(bool forwards);
32
33 /// Check if the direction to use in the \a SBTraceCursor::Next() method is
34 /// forwards.
35 ///
36 /// \return
37 /// \b true if the current direction is forwards, \b false if backwards.
38 bool IsForwards() const;
39
40 /// Move the cursor to the next item (instruction or error).
41 ///
42 /// Direction:
43 /// The traversal is done following the current direction of the trace. If
44 /// it is forwards, the instructions are visited forwards
45 /// chronologically. Otherwise, the traversal is done in
46 /// the opposite direction. By default, a cursor moves backwards unless
47 /// changed with \a SBTraceCursor::SetForwards().
48 void Next();
49
50 /// \return
51 /// \b true if the cursor is pointing to a valid item. \b false if the
52 /// cursor has reached the end of the trace.
53 bool HasValue() const;
54
55 /// Instruction identifiers:
56 ///
57 /// When building complex higher level tools, fast random accesses in the
58 /// trace might be needed, for which each instruction requires a unique
59 /// identifier within its thread trace. For example, a tool might want to
60 /// repeatedly inspect random consecutive portions of a trace. This means that
61 /// it will need to first move quickly to the beginning of each section and
62 /// then start its iteration. Given that the number of instructions can be in
63 /// the order of hundreds of millions, fast random access is necessary.
64 ///
65 /// An example of such a tool could be an inspector of the call graph of a
66 /// trace, where each call is represented with its start and end instructions.
67 /// Inspecting all the instructions of a call requires moving to its first
68 /// instruction and then iterating until the last instruction, which following
69 /// the pattern explained above.
70 ///
71 /// Instead of using 0-based indices as identifiers, each Trace plug-in can
72 /// decide the nature of these identifiers and thus no assumptions can be made
73 /// regarding their ordering and sequentiality. The reason is that an
74 /// instruction might be encoded by the plug-in in a way that hides its actual
75 /// 0-based index in the trace, but it's still possible to efficiently find
76 /// it.
77 ///
78 /// Requirements:
79 /// - For a given thread, no two instructions have the same id.
80 /// - In terms of efficiency, moving the cursor to a given id should be as
81 /// fast as possible, but not necessarily O(1). That's why the recommended
82 /// way to traverse sequential instructions is to use the \a
83 /// SBTraceCursor::Next() method and only use \a SBTraceCursor::GoToId(id)
84 /// sparingly.
85
86 /// Make the cursor point to the item whose identifier is \p id.
87 ///
88 /// \return
89 /// \b true if the given identifier exists and the cursor effectively
90 /// moved to it. Otherwise, \b false is returned and the cursor now points
91 /// to an invalid item, i.e. calling \a HasValue() will return \b false.
92 bool GoToId(lldb::user_id_t id);
93
94 /// \return
95 /// \b true if and only if there's an instruction item with the given \p
96 /// id.
97 bool HasId(lldb::user_id_t id) const;
98
99 /// \return
100 /// A unique identifier for the instruction or error this cursor is
101 /// pointing to.
102 lldb::user_id_t GetId() const;
103 /// \}
104
105 /// Make the cursor point to an item in the trace based on an origin point and
106 /// an offset.
107 ///
108 /// The resulting position of the trace is
109 /// origin + offset
110 ///
111 /// If this resulting position would be out of bounds, the trace then points
112 /// to an invalid item, i.e. calling \a HasValue() returns \b false.
113 ///
114 /// \param[in] offset
115 /// How many items to move forwards (if positive) or backwards (if
116 /// negative) from the given origin point. For example, if origin is \b
117 /// End, then a negative offset would move backward in the trace, but a
118 /// positive offset would move past the trace to an invalid item.
119 ///
120 /// \param[in] origin
121 /// The reference point to use when moving the cursor.
122 ///
123 /// \return
124 /// \b true if and only if the cursor ends up pointing to a valid item.
125 bool Seek(int64_t offset, lldb::TraceCursorSeekType origin);
126
127 /// Trace item information (instructions, errors and events)
128 /// \{
129
130 /// \return
131 /// The kind of item the cursor is pointing at.
132 lldb::TraceItemKind GetItemKind() const;
133
134 /// \return
135 /// Whether the cursor points to an error or not.
136 bool IsError() const;
137
138 /// \return
139 /// The error message the cursor is pointing at.
140 const char *GetError() const;
141
142 /// \return
143 /// Whether the cursor points to an event or not.
144 bool IsEvent() const;
145
146 /// \return
147 /// The specific kind of event the cursor is pointing at.
148 lldb::TraceEvent GetEventType() const;
149
150 /// \return
151 /// A human-readable description of the event this cursor is pointing at.
152 const char *GetEventTypeAsString() const;
153
154 /// \return
155 /// Whether the cursor points to an instruction.
156 bool IsInstruction() const;
157
158 /// \return
159 /// The load address of the instruction the cursor is pointing at.
160 lldb::addr_t GetLoadAddress() const;
161
162 /// \return
163 /// The requested CPU id, or LLDB_INVALID_CPU_ID if this information is
164 /// not available for the current item.
165 lldb::cpu_id_t GetCPU() const;
166
167 bool IsValid() const;
168
169 explicit operator bool() const;
170
171protected:
172 lldb::TraceCursorSP m_opaque_sp;
173};
174} // namespace lldb
175
176#endif // LLDB_API_SBTRACECURSOR_H
#define LLDB_API
Definition: SBDefines.h:26
lldb::TraceCursorSP m_opaque_sp
SBTraceCursor(lldb::TraceCursorSP trace_cursor_sp)
Create a cursor that initially points to the end of the trace, i.e.
Definition: SBAddress.h:15
TraceEvent
Events that might happen during a trace session.
TraceCursorSeekType
Enum to indicate the reference point when invoking TraceCursor::Seek().
uint64_t user_id_t
Definition: lldb-types.h:80
uint64_t addr_t
Definition: lldb-types.h:79