SBTraceCursor#

class lldb.SBTraceCursor#

Represents a trace cursor.

Methods Summary

`GetCPU`()	rtype: int
`GetError`()	rtype: string
`GetEventType`()	rtype: int
`GetEventTypeAsString`()	rtype: string
`GetId`()	rtype: int
`GetItemKind`()	Trace item information (instructions, errors and events)
`GetLoadAddress`()	rtype: int
`GoToId`(id)	Instruction identifiers:
`HasId`(id)	rtype: boolean
`HasValue`()	rtype: boolean
`IsError`()	rtype: boolean
`IsEvent`()	rtype: boolean
`IsForwards`()	Check if the direction to use in the SBTraceCursor::Next() method is forwards.
`IsInstruction`()	rtype: boolean
`IsValid`(SBTraceCursor self)
`Next`()	Move the cursor to the next item (instruction or error).
`Seek`(offset, origin)	Make the cursor point to an item in the trace based on an origin point and an offset.
`SetForwards`(forwards)	Set the direction to use in the SBTraceCursor::Next() method.

Methods Documentation

GetCPU()#

Return type:: int
Returns:: The requested CPU id, or LLDB_INVALID_CPU_ID if this information is not available for the current item.

GetError()#

Return type:: string
Returns:: The error message the cursor is pointing at.

GetEventType()#

Return type:: int
Returns:: The specific kind of event the cursor is pointing at.

GetEventTypeAsString()#

Return type:: string
Returns:: A human-readable description of the event this cursor is pointing at.

GetId()#

Return type:: int
Returns:: A unique identifier for the instruction or error this cursor is pointing to.

GetItemKind()#

Trace item information (instructions, errors and events)

Return type:: int
Returns:: The kind of item the cursor is pointing at.

GetLoadAddress()#

Return type:: int
Returns:: The load address of the instruction the cursor is pointing at.

GoToId(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.

rtype:: boolean
return:: 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.

HasId(id)#

Return type:

boolean

Returns:

true if and only if there’s an instruction item with the given

id.

HasValue()#

Return type:: boolean
Returns:: true if the cursor is pointing to a valid item. false if the cursor has reached the end of the trace.

IsError()#

Return type:: boolean
Returns:: Whether the cursor points to an error or not.

IsEvent()#

Return type:: boolean
Returns:: Whether the cursor points to an event or not.

IsForwards()#

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

Return type:: boolean
Returns:: true if the current direction is forwards, false if backwards.

IsInstruction()#

Return type:: boolean
Returns:: Whether the cursor points to an instruction.

IsValid(SBTraceCursor self) → bool#

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().

Seek(offset, 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:

offset (int, in) –

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.
origin (int, in) – The reference point to use when moving the cursor.

Return type:

boolean

Returns:

true if and only if the cursor ends up pointing to a valid item.

SetForwards(forwards)#

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

Parameters:: forwards (boolean, in) – If true, then the traversal will be forwards, otherwise backwards.