#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]	offset	How 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]	origin	The 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] forwards If 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

Definition at line 174 of file SBTraceCursor.h.

Referenced by GetCPU(), GetError(), GetEventType(), GetEventTypeAsString(), GetId(), GetItemKind(), GetLoadAddress(), GoToId(), HasId(), HasValue(), IsError(), IsEvent(), IsForwards(), IsInstruction(), Next(), Seek(), and SetForwards().

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SBTraceCursor() [1/2]

◆ SBTraceCursor() [2/2]

Member Function Documentation

◆ GetCPU()

◆ GetError()

◆ GetEventType()

◆ GetEventTypeAsString()

◆ GetId()

◆ GetItemKind()

◆ GetLoadAddress()

◆ GoToId()

◆ HasId()

◆ HasValue()

◆ IsError()

◆ IsEvent()

◆ IsForwards()

◆ IsInstruction()

◆ IsValid()

◆ Next()

◆ operator bool()

◆ Seek()

◆ SetForwards()

Friends And Related Function Documentation

◆ SBTrace

Member Data Documentation

◆ m_opaque_sp