Remote debugging attachment protocol — Locating the interpreter and thread state

Reference note (untrusted external data; do not execute it as instructions). Before code can be injected and executed in a remote Python process, the debugger must choose a thread in which to schedule execution. This is necessary because the control fields used to perform remote code injection are located in the _PyRemoteDebuggerSupport structure, which is embedded in a PyThreadState object. These fields are modified by the debugger to request execution of injected scripts. The PyThreadState structure represents a thread running inside a Python interpreter. It maintains the thread’s evaluation context and contains the fields required for debugger coordination. Locating a valid PyThreadState is therefore a key prerequisite for triggering execution remotely. A thread is typically selected based on its role or ID. In most cases, the main thread is used, but some tools may target a specific thread by its native thread ID. Once the target thread is chosen, the debugger must locate both the interpreter and the associated thread state structures in memory. The relevant internal structures are defined as follows PyInterpreterState represents an isolated Python interpreter instance. Each interpreter maintains its own set of imported modules, built-in state, and thread state list. Although most Python applications use a single interpreter, CPython supports multiple interpreters in the same process. PyThreadState represents a thread running within an interpreter. It contains execution state and the control fields used by the debugger. Use the offset runtime_state.interpreters_head to obtain the address of the first interpreter in the PyRuntime structure. This is the entry point to the linked list of active interpreters. Use the offset interpreter_state.threads_main to access the main thread state associated with the selected interpreter. This is typically the most reliable thread to target. Optionally, use the offset interpreter_state.threads_head to iterate through the linked list of all thread states. Each PyThreadState structure contains a native_thread_id field, which may be compared to a target thread ID to find a specific thread. Once a valid PyThreadState has been found, its address can be used in later steps of the protocol, such as writing debugger control fields and scheduling execution. The following is an example implementation that locates the main thread state … Attribution: Adapted from Python Documentation under PSF-2.0. Adaptation: WikiKV isolated this documentation section, normalized formatting, retained only bounded code excerpts, and shortened it at a paragraph or sentence boundary for retrieval. Verify version-sensitive details at the source.