Med Ismail Bennani
694db4d296
This patch adds type annotations to every method (parameters and return types) and every `self.<name>` attribute of the scripted extension base classes shipped under `lldb/examples/python/templates/`. Extension authors reading the base classes -- or an IDE navigating them -- can now see the `lldb.SB*` contract each method exposes without having to cross-reference the docstring. `scripting extension generate` also picks the annotations up: derived class docstrings advertise each inherited attribute together with its declared type, and the generated method signatures carry their parameter and return annotations too. The classes covered are `ScriptedProcess`, `ScriptedThread`, `ScriptedFrame`, `PassthroughScriptedProcess`, `PassthroughScriptedThread`, `ScriptedFrameProvider`, `ScriptedBreakpointResolver`, `ScriptedThreadPlan`, `ScriptedHook`, `ScriptedPlatform`, and `OperatingSystem`. Signed-off-by: Med Ismail Bennani <ismail@bennani.ma> (cherry picked from commit f10ede511119d7f31f2c6aaca3cbcb1ea00164ce)
73 lines
2.6 KiB
Python
73 lines
2.6 KiB
Python
from abc import abstractmethod
|
|
|
|
import lldb
|
|
|
|
|
|
class ScriptedThreadPlan:
|
|
"""
|
|
Class that provides data for an instance of a LLDB 'ScriptedThreadPlan' plug-in class used to construct custom stepping logic.
|
|
|
|
"""
|
|
|
|
thread_plan: lldb.SBThreadPlan
|
|
|
|
def __init__(self, thread_plan: lldb.SBThreadPlan):
|
|
"""Initialization needs a valid lldb.SBThreadPlan object. This plug-in will get created after a live process is valid and has stopped.
|
|
|
|
Args:
|
|
thread_plan (lldb.SBThreadPlan): The underlying `ThreadPlan` that is pushed onto the plan stack.
|
|
"""
|
|
self.thread_plan = thread_plan
|
|
|
|
def explains_stop(self, event: lldb.SBEvent) -> bool:
|
|
"""Each plan is asked from youngest to oldest if it "explains" the stop. The first plan to claim the stop wins.
|
|
|
|
Args:
|
|
event (lldb.SBEvent): The process stop event.
|
|
|
|
Returns:
|
|
bool: `True` if this stop could be claimed by this thread plan, `False` otherwise.
|
|
Defaults to `True`.
|
|
"""
|
|
return True
|
|
|
|
def is_stale(self) -> bool:
|
|
"""If your plan is no longer relevant (for instance, you were stepping in a particular stack frame, but some other operation pushed that frame off the stack) return True and your plan will get popped.
|
|
|
|
Returns:
|
|
bool: `True` if this thread plan is stale, `False` otherwise.
|
|
Defaults to `False`.
|
|
"""
|
|
return False
|
|
|
|
def should_stop(self, event: lldb.SBEvent) -> bool:
|
|
"""Whether this thread plan should stop and return control to the user.
|
|
If your plan is done at this point, call SetPlanComplete on your thread plan instance. Also, do any work you need here to set up the next stage of stepping.
|
|
|
|
Args:
|
|
event (lldb.SBEvent): The process stop event.
|
|
|
|
Returns:
|
|
bool: `True` if this plan wants to stop and return control to the user at this point, `False` otherwise.
|
|
Defaults to `False`.
|
|
"""
|
|
self.thread_plan.SetPlanComplete(True)
|
|
return True
|
|
|
|
def should_step(self) -> bool:
|
|
"""Whether this thread plan should instruction step one instruction, or continue till the next breakpoint is hit.
|
|
|
|
Returns:
|
|
bool: `True` if this plan will instruction step one instruction, `False` otherwise.
|
|
Defaults to `True`.
|
|
"""
|
|
return True
|
|
|
|
def stop_description(self, stream: lldb.SBStream) -> None:
|
|
"""Customize the thread plan stop reason when the thread plan is complete.
|
|
|
|
Args:
|
|
stream (lldb.SBStream): The stream containing the stop description.
|
|
"""
|
|
pass
|