.tgt.heapykinds.RootStateType

RootStateType

The type of an object with special functionality that gives access to internals of the Python interpreter and thread structures. It is used as a top level root when traversing the heap to make sure to find some special objects that may otherwise be hidden.

There are no references from the RootState object to the special objects. But the heap traversal and related functions defined for RootStateType look into the Python interpreter and thread structures. The visibility is controlled by options set in the HeapView object which is passed to the traversal function. This makes it possible to hide an interpreter and/or some frames referring to system objects that should not be traversed. (See the attributes 'is_hiding_calling_interpreter' and 'limitframe' in HeapView.)

The objects found in interpreter and thread structures are related to the RootState object via attributes with special names. These names have a special form which will be described below. The name starts with either an interpreter designator or a thread designator. It is then followed by the name of a member in the corresponding interpreter or thread structure. These names are the same as the names of the members in the C structures defining them. Some of the names may be dependent on the Python interpreter version used.

The attribute names are used for two purposes:

• To be the name used in the result of the 'relate' operation between the RootState object and some object that is referred to via an internal Python interpreter or thread structure.
• To be used as attribute names when selecting objects from the RootState object. This may be used to get at such an object knowing only its attribute name.

An attribute name is of one of the following three forms.

i<interpreter number>_<interpreter attribute>

i<interpreter number>_t<thread number>_<thread attribute>

i<interpreter number>_t<thread number>_f<frame number>

<interpreter number>

The interpreter number identifies a particular interpreter structure. Often there is only one interpreter used, in which case the number is 0. It is possible to use more than one interpreter. The interpreters are then numbered from 0 and up in the order they were started. [This applies as long as no interpreter is terminated while there is still a newer interpreter running. Then the newer interpreters will be renumbered. If this is found to be a problem, a solution may be devised for a newer release.]

<interpreter attribute>

The interpreter attribute is a member with PyObject pointer type in the PyInterpreterState structure and can be, but not limited to, one of the following:

• modules
• sysdict
• builtins
• codec_search_path
• codec_search_cache
• codec_error_registry

<thread number>

The thread numbers are taken from the thread identity number assigned by Python. [ In older versions without thread identity numbers the hex address will be used.]

<thread attribute>

The thread attribute is a member with PyObject pointer type in the PyThreadState structure and can be, but not limited to, one of the following:

• c_profileobj
• c_traceobj
• curexc_type
• curexc_value
• curexc_traceback
• exc_type
• exc_value
• exc_traceback
• dict
• async_exc

<frame number>

The frame list is treated specially. The frame list is continually changed and the object that the frame member points to is not valid for long enough to be useful. Therefore frames are referred to by a special designator using the format shown above with a frame number. The frame number is the number of the frame starting from 0 but counting in the reversed order of the frame list. Thus the first started frame is 0, and in general the most recent frame has a number that is the number of frames it has before it in call order.