ScriptedStackFrameRecognizer

class lldb.plugins.scripted_stackframe_recognizer.ScriptedStackFrameRecognizer

The base class for a scripted stack frame recognizer.

A frame recognizer inspects a stack frame at stop time and can:

• attach recognized arguments to it (surfaced the same way as args for unrecognized frames);

• hide the frame from backtraces;

• override the stop description reported for it;

• expose an exception object associated with it (e.g. a runtime’s thrown value);

• redirect auto-selection to a more relevant frame (e.g. bounce past a language-runtime trampoline).

Register the recognizer with frame recognizer add -l <ClassName> ....

Every method is optional: a recognizer only implements the ones it cares about. A recognizer that just hides frames can implement only should_hide; one that surfaces exception info can implement only get_exception and get_stop_description.

Methods Summary

get_exception(frame)	Get the exception value associated with this recognized frame, if any (e.g. the exception object at a language runtime's throw site).
get_recognized_arguments(frame)	Get the arguments recognized for this frame.
get_stop_description(frame)	Get the stop description to surface for this recognized frame, replacing whatever description lldb would have printed.
select_most_relevant_frame(frame)	Pick a different frame to auto-select when the process stops in this recognized frame.
should_hide(frame)	Whether this frame should be hidden when displaying backtraces.

Methods Documentation

get_exception(frame: SBFrame) → SBValue | None

Get the exception value associated with this recognized frame, if any (e.g. the exception object at a language runtime’s throw site).

Parameters:

frame (lldb.SBFrame) – The recognized frame.

Returns:

The exception value, or None if this frame doesn’t correspond to an exception.

Return type:

lldb.SBValue

get_recognized_arguments(frame: SBFrame) → list

Get the arguments recognized for this frame.

Parameters:

frame (lldb.SBFrame) – The frame to inspect.

Returns:

The recognized arguments, or an empty list if none could be recognized.

Return type:

list of lldb.SBValue

get_stop_description(frame: SBFrame) → str

Get the stop description to surface for this recognized frame, replacing whatever description lldb would have printed.

Parameters:

frame (lldb.SBFrame) – The recognized frame.

Returns:

The stop description, or the empty string to keep the default.

Return type:

str

select_most_relevant_frame(frame: SBFrame) → SBFrame | None

Pick a different frame to auto-select when the process stops in this recognized frame. Useful when the recognized frame is trampoline code that the user probably didn’t want to land in (e.g. a language runtime’s exception-throw path).

Parameters:

frame (lldb.SBFrame) – The recognized frame.

Returns:

The frame to select instead, or None to keep the default selection.

Return type:

lldb.SBFrame

should_hide(frame: SBFrame) → bool

Whether this frame should be hidden when displaying backtraces.

Parameters:

frame (lldb.SBFrame) – The frame to inspect.

Returns:

True if this frame should be hidden, False otherwise. Defaults to False.

Return type:

bool