LLDB mainline
Public Member Functions | List of all members
lldb::SBTraceCursor Class Reference

#include <SBTraceCursor.h>

Public Member Functions

 SBTraceCursor ()
 Default constructor for an invalid SBTraceCursor object.
 
void SetForwards (bool forwards)
 Set the direction to use in the SBTraceCursor::Next() method.
 
bool IsForwards () const
 Check if the direction to use in the SBTraceCursor::Next() method is forwards.
 
void Next ()
 Move the cursor to the next item (instruction or error).
 
bool HasValue () const
 
bool GoToId (lldb::user_id_t id)
 Instruction identifiers:
 
bool HasId (lldb::user_id_t id) const
 
lldb::user_id_t GetId () const
 
bool Seek (int64_t offset, lldb::TraceCursorSeekType origin)
 Make the cursor point to an item in the trace based on an origin point and an offset.
 
class SBTrace
 
lldb::TraceCursorSP m_opaque_sp
 
lldb::TraceItemKind GetItemKind () const
 Trace item information (instructions, errors and events)
 
bool IsError () const
 
const char * GetError () const
 
bool IsEvent () const
 
lldb::TraceEvent GetEventType () const
 
const char * GetEventTypeAsString () const
 
bool IsInstruction () const
 
lldb::addr_t GetLoadAddress () const
 
lldb::cpu_id_t GetCPU () const
 
bool IsValid () const
 
 operator bool () const
 
 SBTraceCursor (lldb::TraceCursorSP trace_cursor_sp)
 Create a cursor that initially points to the end of the trace, i.e.
 

Detailed Description

Definition at line 18 of file SBTraceCursor.h.

Constructor & Destructor Documentation

◆ SBTraceCursor() [1/2]

SBTraceCursor::SBTraceCursor ( )

Default constructor for an invalid SBTraceCursor object.

Definition at line 18 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA.

◆ SBTraceCursor() [2/2]

SBTraceCursor::SBTraceCursor ( lldb::TraceCursorSP  trace_cursor_sp)
protected

Create a cursor that initially points to the end of the trace, i.e.

the most recent item.

Definition at line 20 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA.

Member Function Documentation

◆ GetCPU()

lldb::cpu_id_t SBTraceCursor::GetCPU ( ) const
Returns
The requested CPU id, or LLDB_INVALID_CPU_ID if this information is not available for the current item.

Definition at line 121 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA, and m_opaque_sp.

◆ GetError()

const char * SBTraceCursor::GetError ( ) const
Returns
The error message the cursor is pointing at.

Definition at line 85 of file SBTraceCursor.cpp.

References lldb_private::ConstString::GetCString(), LLDB_INSTRUMENT_VA, and m_opaque_sp.

◆ GetEventType()

lldb::TraceEvent SBTraceCursor::GetEventType ( ) const
Returns
The specific kind of event the cursor is pointing at.

Definition at line 97 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA, and m_opaque_sp.

◆ GetEventTypeAsString()

const char * SBTraceCursor::GetEventTypeAsString ( ) const
Returns
A human-readable description of the event this cursor is pointing at.

Definition at line 103 of file SBTraceCursor.cpp.

References lldb_private::ConstString::GetCString(), LLDB_INSTRUMENT_VA, and m_opaque_sp.

◆ GetId()

lldb::user_id_t SBTraceCursor::GetId ( ) const
Returns
A unique identifier for the instruction or error this cursor is pointing to.

Definition at line 61 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA, and m_opaque_sp.

◆ GetItemKind()

lldb::TraceItemKind SBTraceCursor::GetItemKind ( ) const

Trace item information (instructions, errors and events)

Returns
The kind of item the cursor is pointing at.

Definition at line 73 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA, and m_opaque_sp.

◆ GetLoadAddress()

lldb::addr_t SBTraceCursor::GetLoadAddress ( ) const
Returns
The load address of the instruction the cursor is pointing at.

Definition at line 115 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA, and m_opaque_sp.

◆ GoToId()

bool SBTraceCursor::GoToId ( lldb::user_id_t  id)

Instruction identifiers:

When building complex higher level tools, fast random accesses in the trace might be needed, for which each instruction requires a unique identifier within its thread trace. For example, a tool might want to repeatedly inspect random consecutive portions of a trace. This means that it will need to first move quickly to the beginning of each section and then start its iteration. Given that the number of instructions can be in the order of hundreds of millions, fast random access is necessary.

An example of such a tool could be an inspector of the call graph of a trace, where each call is represented with its start and end instructions. Inspecting all the instructions of a call requires moving to its first instruction and then iterating until the last instruction, which following the pattern explained above.

Instead of using 0-based indices as identifiers, each Trace plug-in can decide the nature of these identifiers and thus no assumptions can be made regarding their ordering and sequentiality. The reason is that an instruction might be encoded by the plug-in in a way that hides its actual 0-based index in the trace, but it's still possible to efficiently find it.

Requirements:

  • For a given thread, no two instructions have the same id.
  • In terms of efficiency, moving the cursor to a given id should be as fast as possible, but not necessarily O(1). That's why the recommended way to traverse sequential instructions is to use the SBTraceCursor::Next() method and only use SBTraceCursor::GoToId(id) sparingly. Make the cursor point to the item whose identifier is id.
Returns
true if the given identifier exists and the cursor effectively moved to it. Otherwise, false is returned and the cursor now points to an invalid item, i.e. calling HasValue() will return false.

Definition at line 49 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA, and m_opaque_sp.

◆ HasId()

bool SBTraceCursor::HasId ( lldb::user_id_t  id) const
Returns
true if and only if there's an instruction item with the given id.

Definition at line 55 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA, and m_opaque_sp.

◆ HasValue()

bool SBTraceCursor::HasValue ( ) const
Returns
true if the cursor is pointing to a valid item. false if the cursor has reached the end of the trace.

Definition at line 43 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA, and m_opaque_sp.

◆ IsError()

bool SBTraceCursor::IsError ( ) const
Returns
Whether the cursor points to an error or not.

Definition at line 79 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA, and m_opaque_sp.

◆ IsEvent()

bool SBTraceCursor::IsEvent ( ) const
Returns
Whether the cursor points to an event or not.

Definition at line 91 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA, and m_opaque_sp.

◆ IsForwards()

bool SBTraceCursor::IsForwards ( ) const

Check if the direction to use in the SBTraceCursor::Next() method is forwards.

Returns
true if the current direction is forwards, false if backwards.

Definition at line 31 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA, and m_opaque_sp.

◆ IsInstruction()

bool SBTraceCursor::IsInstruction ( ) const
Returns
Whether the cursor points to an instruction.

Definition at line 109 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA, and m_opaque_sp.

◆ IsValid()

bool SBTraceCursor::IsValid ( ) const

Definition at line 127 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA.

◆ Next()

void SBTraceCursor::Next ( )

Move the cursor to the next item (instruction or error).

Direction: The traversal is done following the current direction of the trace. If it is forwards, the instructions are visited forwards chronologically. Otherwise, the traversal is done in the opposite direction. By default, a cursor moves backwards unless changed with SBTraceCursor::SetForwards().

Definition at line 37 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA, and m_opaque_sp.

◆ operator bool()

SBTraceCursor::operator bool ( ) const
explicit

Definition at line 133 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA.

◆ Seek()

bool SBTraceCursor::Seek ( int64_t  offset,
lldb::TraceCursorSeekType  origin 
)

Make the cursor point to an item in the trace based on an origin point and an offset.

The resulting position of the trace is origin + offset

If this resulting position would be out of bounds, the trace then points to an invalid item, i.e. calling HasValue() returns false.

Parameters
[in]offsetHow many items to move forwards (if positive) or backwards (if negative) from the given origin point. For example, if origin is End, then a negative offset would move backward in the trace, but a positive offset would move past the trace to an invalid item.
[in]originThe reference point to use when moving the cursor.
Returns
true if and only if the cursor ends up pointing to a valid item.

Definition at line 67 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA, and m_opaque_sp.

◆ SetForwards()

void SBTraceCursor::SetForwards ( bool  forwards)

Set the direction to use in the SBTraceCursor::Next() method.

Parameters
[in]forwardsIf true, then the traversal will be forwards, otherwise backwards.

Definition at line 25 of file SBTraceCursor.cpp.

References LLDB_INSTRUMENT_VA, and m_opaque_sp.

Friends And Related Function Documentation

◆ SBTrace

friend class SBTrace
friend

Definition at line 168 of file SBTraceCursor.h.

Member Data Documentation

◆ m_opaque_sp

lldb::TraceCursorSP lldb::SBTraceCursor::m_opaque_sp
protected

The documentation for this class was generated from the following files: