EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2026-05-10 08:42:43
0001 //===-- SBTraceCursor.h -----------------------------------------*- C++ -*-===// 0002 // 0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 0004 // See https://llvm.org/LICENSE.txt for license information. 0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 0006 // 0007 //===----------------------------------------------------------------------===// 0008 0009 #ifndef LLDB_API_SBTRACECURSOR_H 0010 #define LLDB_API_SBTRACECURSOR_H 0011 0012 #include "lldb/API/SBDefines.h" 0013 #include "lldb/API/SBError.h" 0014 #include "lldb/API/SBExecutionContext.h" 0015 0016 namespace lldb { 0017 0018 class LLDB_API SBTraceCursor { 0019 public: 0020 /// Default constructor for an invalid \a SBTraceCursor object. 0021 SBTraceCursor(); 0022 0023 /// Set the direction to use in the \a SBTraceCursor::Next() method. 0024 /// 0025 /// \param[in] forwards 0026 /// If \b true, then the traversal will be forwards, otherwise backwards. 0027 void SetForwards(bool forwards); 0028 0029 /// Check if the direction to use in the \a SBTraceCursor::Next() method is 0030 /// forwards. 0031 /// 0032 /// \return 0033 /// \b true if the current direction is forwards, \b false if backwards. 0034 bool IsForwards() const; 0035 0036 /// Move the cursor to the next item (instruction or error). 0037 /// 0038 /// Direction: 0039 /// The traversal is done following the current direction of the trace. If 0040 /// it is forwards, the instructions are visited forwards 0041 /// chronologically. Otherwise, the traversal is done in 0042 /// the opposite direction. By default, a cursor moves backwards unless 0043 /// changed with \a SBTraceCursor::SetForwards(). 0044 void Next(); 0045 0046 /// \return 0047 /// \b true if the cursor is pointing to a valid item. \b false if the 0048 /// cursor has reached the end of the trace. 0049 bool HasValue() const; 0050 0051 /// Instruction identifiers: 0052 /// 0053 /// When building complex higher level tools, fast random accesses in the 0054 /// trace might be needed, for which each instruction requires a unique 0055 /// identifier within its thread trace. For example, a tool might want to 0056 /// repeatedly inspect random consecutive portions of a trace. This means that 0057 /// it will need to first move quickly to the beginning of each section and 0058 /// then start its iteration. Given that the number of instructions can be in 0059 /// the order of hundreds of millions, fast random access is necessary. 0060 /// 0061 /// An example of such a tool could be an inspector of the call graph of a 0062 /// trace, where each call is represented with its start and end instructions. 0063 /// Inspecting all the instructions of a call requires moving to its first 0064 /// instruction and then iterating until the last instruction, which following 0065 /// the pattern explained above. 0066 /// 0067 /// Instead of using 0-based indices as identifiers, each Trace plug-in can 0068 /// decide the nature of these identifiers and thus no assumptions can be made 0069 /// regarding their ordering and sequentiality. The reason is that an 0070 /// instruction might be encoded by the plug-in in a way that hides its actual 0071 /// 0-based index in the trace, but it's still possible to efficiently find 0072 /// it. 0073 /// 0074 /// Requirements: 0075 /// - For a given thread, no two instructions have the same id. 0076 /// - In terms of efficiency, moving the cursor to a given id should be as 0077 /// fast as possible, but not necessarily O(1). That's why the recommended 0078 /// way to traverse sequential instructions is to use the \a 0079 /// SBTraceCursor::Next() method and only use \a SBTraceCursor::GoToId(id) 0080 /// sparingly. 0081 0082 /// Make the cursor point to the item whose identifier is \p id. 0083 /// 0084 /// \return 0085 /// \b true if the given identifier exists and the cursor effectively 0086 /// moved to it. Otherwise, \b false is returned and the cursor now points 0087 /// to an invalid item, i.e. calling \a HasValue() will return \b false. 0088 bool GoToId(lldb::user_id_t id); 0089 0090 /// \return 0091 /// \b true if and only if there's an instruction item with the given \p 0092 /// id. 0093 bool HasId(lldb::user_id_t id) const; 0094 0095 /// \return 0096 /// A unique identifier for the instruction or error this cursor is 0097 /// pointing to. 0098 lldb::user_id_t GetId() const; 0099 /// \} 0100 0101 /// Make the cursor point to an item in the trace based on an origin point and 0102 /// an offset. 0103 /// 0104 /// The resulting position of the trace is 0105 /// origin + offset 0106 /// 0107 /// If this resulting position would be out of bounds, the trace then points 0108 /// to an invalid item, i.e. calling \a HasValue() returns \b false. 0109 /// 0110 /// \param[in] offset 0111 /// How many items to move forwards (if positive) or backwards (if 0112 /// negative) from the given origin point. For example, if origin is \b 0113 /// End, then a negative offset would move backward in the trace, but a 0114 /// positive offset would move past the trace to an invalid item. 0115 /// 0116 /// \param[in] origin 0117 /// The reference point to use when moving the cursor. 0118 /// 0119 /// \return 0120 /// \b true if and only if the cursor ends up pointing to a valid item. 0121 bool Seek(int64_t offset, lldb::TraceCursorSeekType origin); 0122 0123 /// Trace item information (instructions, errors and events) 0124 /// \{ 0125 0126 /// \return 0127 /// The kind of item the cursor is pointing at. 0128 lldb::TraceItemKind GetItemKind() const; 0129 0130 /// \return 0131 /// Whether the cursor points to an error or not. 0132 bool IsError() const; 0133 0134 /// \return 0135 /// The error message the cursor is pointing at. 0136 const char *GetError() const; 0137 0138 /// \return 0139 /// Whether the cursor points to an event or not. 0140 bool IsEvent() const; 0141 0142 /// \return 0143 /// The specific kind of event the cursor is pointing at. 0144 lldb::TraceEvent GetEventType() const; 0145 0146 /// \return 0147 /// A human-readable description of the event this cursor is pointing at. 0148 const char *GetEventTypeAsString() const; 0149 0150 /// \return 0151 /// Whether the cursor points to an instruction. 0152 bool IsInstruction() const; 0153 0154 /// \return 0155 /// The load address of the instruction the cursor is pointing at. 0156 lldb::addr_t GetLoadAddress() const; 0157 0158 /// \return 0159 /// The requested CPU id, or LLDB_INVALID_CPU_ID if this information is 0160 /// not available for the current item. 0161 lldb::cpu_id_t GetCPU() const; 0162 0163 bool IsValid() const; 0164 0165 explicit operator bool() const; 0166 0167 protected: 0168 friend class SBTrace; 0169 0170 /// Create a cursor that initially points to the end of the trace, i.e. the 0171 /// most recent item. 0172 SBTraceCursor(lldb::TraceCursorSP trace_cursor_sp); 0173 0174 lldb::TraceCursorSP m_opaque_sp; 0175 }; 0176 } // namespace lldb 0177 0178 #endif // LLDB_API_SBTRACECURSOR_H
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|