Erweiterung von Opaque-Typen

In der begrenzten API sind die meisten structs opak: ihre Größe und ihr Speicherlayout werden nicht offengelegt, sodass sie in neuen Versionen von CPython (oder alternativen Implementierungen der C-API) geändert werden können.

Das bedeutet, dass das übliche Muster der Unterklassifizierung – die struct, die für Instanzen des Basis-Typs verwendet wird, als erstes Element der struct, die für Instanzen des abgeleiteten Typs verwendet wird – nicht funktioniert. Zur Veranschaulichung mit Code erweitert das Beispiel aus dem Tutorial PyListObject (PyListObject, list) unter Verwendung der folgenden struct

typedef struct {
    PyListObject list;
    int state;
} SubListObject;

Dies wird in der begrenzten API nicht kompiliert, da PyListObject opak ist (um Änderungen bei der Implementierung von Funktionen und Optimierungen zu ermöglichen).

Stattdessen schlägt diese PEP die Verwendung einer struct mit nur dem in der Unterklasse benötigten Zustand vor, nämlich

typedef struct {
    int state;
} SubListState;

// (or just `typedef int SubListState;` in this case)

Die Unterklasse kann nun vollständig vom Speicherlayout (und der Größe) der Oberklasse entkoppelt werden.

Dies ist heute möglich. Um eine solche struct zu verwenden

• bei der Erstellung der Klasse, verwenden Sie PyListObject->tp_basicsize + sizeof(SubListState) als PyType_Spec.basicsize;
• beim Zugriff auf die Daten, verwenden Sie PyListObject->tp_basicsize als Offset in der Instanz (PyObject*).

Dies hat jedoch Nachteile

• Die basicsize der Basis kann nicht richtig ausgerichtet sein, was auf einigen Architekturen zu Problemen führen kann, wenn sie nicht behoben werden. (Diese Probleme können besonders knifflig sein, wenn sich die Ausrichtung in einer neuen Version ändert.)
• PyTypeObject.tp_basicsize wird in der begrenzten API nicht exponiert, sodass Erweiterungen, die die begrenzte API unterstützen, PyObject_GetAttrString(obj, "__basicsize__") verwenden müssen. Dies ist umständlich und in Randfällen unsicher (das Python-Attribut kann überschrieben werden).
• Variable Objekte werden nicht behandelt (siehe Erweiterung von variablen Objekten unten).

Um dies einfach (und sogar zur *Best Practice* für Projekte, die lose Kopplung gegenüber maximaler Leistung wählen) zu machen, schlägt diese PEP eine API vor, um

1. Geben Sie während der Klassenerstellung an, dass SubListState an PyListObject „angehängt“ werden soll, ohne zusätzliche Details über list zu übergeben. (Der Interpreter selbst erhält alle notwendigen Informationen, wie z. B. tp_basicsize, von der Basis.)

   Dies wird durch eine negative PyType_Spec.basicsize angegeben: -sizeof(SubListState).

2. Erhalten Sie aus einer Instanz und dem PyTypeObject* der Unterklasse einen Zeiger auf die SubListState. Eine neue Funktion, PyObject_GetTypeData, wird dafür hinzugefügt.

Die Basisklasse ist natürlich nicht auf PyListObject beschränkt: Sie kann verwendet werden, um jede Basisklasse zu erweitern, deren Instanz struct opak, über Releases hinweg instabil oder überhaupt nicht exponiert ist – einschließlich type (PyHeapTypeObject) oder Erweiterungen von Drittanbietern (zum Beispiel NumPy-Arrays [1]).

Für Fälle, in denen kein zusätzlicher Zustand benötigt wird, wird eine basicsize von Null zugelassen: In diesem Fall wird die tp_basicsize der Basis geerbt. (Dies funktioniert derzeit, es fehlen jedoch explizite Dokumentation und Tests.)

Die tp_basicsize der neuen Klasse wird auf die berechnete Gesamtgröße gesetzt, sodass Code, der Klassen inspiziert, wie zuvor weiter funktioniert.

Erweiterung von variablen Objekten

Zusätzliche Überlegungen sind erforderlich, um variable-sized objects unter Beibehaltung der losen Kopplung zu unterklassifizieren: die variable Daten können mit den Unterklassen-Daten kollidieren (SubListState im obigen Beispiel).

Derzeit bietet CPython keine Möglichkeit, solche Kollisionen zu verhindern. Daher wird der vorgeschlagene Mechanismus zur Erweiterung von Opaque-Klassen (negativer base->tp_itemsize) standardmäßig fehlschlagen.

Wir könnten hier aufhören, aber da der motivierende Typ – PyHeapTypeObject – variable Größe hat, benötigen wir einen sicheren Weg, um die Unterklassifizierung zu ermöglichen. Ein kurzer Hintergrund zuerst

PyTupleObject:
┌───────────────────┬───┬───┬╌╌╌╌┐
│ PyObject_VAR_HEAD │var. data   │
└───────────────────┴───┴───┴╌╌╌╌┘

tuple subclass:
┌───────────────────┬───┬───┬╌╌╌╌┬─────────────┐
│ PyObject_VAR_HEAD │var. data   │subclass data│
└───────────────────┴───┴───┴╌╌╌╌┴─────────────┘

heap type:
┌───────────────────┬──────────────┬───┬───┬╌╌╌╌┐
│ PyObject_VAR_HEAD │Heap type data│var. data   │
└───────────────────┴──────────────┴───┴───┴╌╌╌╌┘

type subclass:
┌───────────────────┬──────────────┬─────────────┬───┬───┬╌╌╌╌┐
│ PyObject_VAR_HEAD │Heap type data│subclass data│var. data   │
└───────────────────┴──────────────┴─────────────┴───┴───┴╌╌╌╌┘

Relative Member-Offsets

Ein weiteres Puzzleteil ist PyMemberDef.offset. Erweiterungen, die eine unterklassenspezifische struct (SubListState oben) verwenden, erhalten eine Möglichkeit, „relative“ Offsets (Offsets, die von dieser struct ausgehen) anstelle von „absoluten“ (basierend auf der PyObject struct) anzugeben.

Eine Möglichkeit wäre, „relative“ Offsets automatisch anzunehmen, wenn eine Klasse mit der neuen API erstellt wird. Diese implizite Annahme wäre jedoch zu überraschend.

Um expliziter zu sein, schlägt diese PEP ein neues Flag für „relative“ Offsets vor. Zumindest anfangs dient dieses Flag nur als Prüfung gegen Missbrauch (und als Hinweis für Gutachter). Es muss vorhanden sein, wenn es mit der neuen API verwendet wird, und darf sonst nicht verwendet werden.

Relative basicsize

Das Mitglied basicsize von PyType_Spec darf null oder negativ sein. In diesem Fall gibt sein absoluter Wert an, wie viel *zusätzlicher* Speicherplatz Instanzen der neuen Klasse benötigen, zusätzlich zur basicsize der Basisklasse. Das heißt, die basicsize der resultierenden Klasse wird sein:

type->tp_basicsize = _align(base->tp_basicsize) + _align(-spec->basicsize);

wobei _align auf ein Vielfaches von alignof(max_align_t) aufrundet.

Wenn spec->basicsize Null ist, wird die basicsize direkt geerbt, d. h. auf base->tp_basicsize gesetzt, ohne Ausrichtung. (Dies funktioniert bereits; explizite Tests und Dokumentation werden hinzugefügt.)

Auf einer Instanz ist der spezifische Speicherbereich der Unterklasse – d. h. der „zusätzliche Speicher“, den die Unterklasse zusätzlich zu ihrer Basis reserviert – über eine neue Funktion, PyObject_GetTypeData, verfügbar. In CPython wird diese Funktion wie folgt definiert:

void *
PyObject_GetTypeData(PyObject *obj, PyTypeObject *cls) {
    return (char *)obj + _align(cls->tp_base->tp_basicsize);
}

Eine weitere Funktion wird hinzugefügt, um die Größe dieses Speicherbereichs abzurufen:

Py_ssize_t
PyType_GetTypeDataSize(PyTypeObject *cls) {
    return cls->tp_basicsize - _align(cls->tp_base->tp_basicsize);
}

Das Ergebnis kann höher sein als durch -basicsize angefordert. Es ist sicher, alles zu verwenden (z. B. mit memset).

Die neuen *Get*-Funktionen haben einen wichtigen Vorbehalt, der in der Dokumentation darauf hingewiesen wird: Sie dürfen nur für Klassen verwendet werden, die mit negativer PyType_Spec.basicsize erstellt wurden. Für andere Klassen ist ihr Verhalten undefiniert. (Beachten Sie, dass dies ermöglicht, dass der obige Code annimmt, dass cls->tp_base nicht NULL ist.)

itemsize erben

Wenn spec->itemsize Null ist, wird tp_itemsize von der Basis geerbt. (Dies funktioniert bereits; explizite Tests und Dokumentation werden hinzugefügt.)

Ein neues Typ-Flag, Py_TPFLAGS_ITEMS_AT_END, wird hinzugefügt. Dieses Flag kann nur für Typen mit einer tp_itemsize ungleich Null gesetzt werden. Es zeigt an, dass der variable Teil einer Instanz am Ende des Speichers der Instanz gespeichert wird.

Der Standard-Metatyp (PyType_Type) setzt dieses Flag.

Eine neue Funktion, PyObject_GetItemData, wird hinzugefügt, um auf den für variable Inhalte von Typen mit dem neuen Flag reservierten Speicher zuzugreifen. In CPython wird sie wie folgt definiert:

void *
PyObject_GetItemData(PyObject *obj) {
    if (!PyType_HasFeature(Py_TYPE(obj), Py_TPFLAGS_ITEMS_AT_END) {
        <fail with TypeError>
    }
    return (char *)obj + Py_TYPE(obj)->tp_basicsize;
}

Diese Funktion wird zunächst nicht in die begrenzte API aufgenommen.

Das Erweitern einer Klasse mit positiver base->itemsize unter Verwendung einer negativen spec->basicsize schlägt fehl, es sei denn, Py_TPFLAGS_ITEMS_AT_END ist gesetzt, entweder auf der Basis oder in spec->flags. (Siehe Erweiterung von variablen Objekten für eine vollständige Erklärung.)

Das Erweitern einer Klasse mit positiver spec->itemsize unter Verwendung einer negativen spec->basicsize schlägt fehl.

Relative Member-Offsets

Bei Typen, die mit negativer PyType_Spec.basicsize definiert sind, müssen die Offsets der über Py_tp_members definierten Member relativ zu den zusätzlichen Unterklassendaten und nicht zur vollständigen PyObject struct sein. Dies wird durch ein neues Flag in PyMemberDef.flags angezeigt: Py_RELATIVE_OFFSET.

In der anfänglichen Implementierung ist das neue Flag redundant. Es dient nur dazu, die geänderte Bedeutung des Offsets klarzustellen und Fehler zu vermeiden. Es ist ein Fehler, Py_RELATIVE_OFFSET nicht mit negativer basicsize zu verwenden, und es ist ein Fehler, es in einem anderen Kontext zu verwenden (d. h. direkte oder indirekte Aufrufe von PyDescr_NewMember, PyMember_GetOne, PyMember_SetOne).

CPython passt den Offset an und löscht das Flag Py_RELATIVE_OFFSET bei der Initialisierung eines Typs. Das bedeutet, dass

• die tp_members des erstellten Typs nicht mit dem Py_tp_members-Slot der Eingabedefinition übereinstimmen und
• jeglicher Code, der tp_members liest, das Flag nicht behandeln muss.

Ausrichtung & Leistung

Die vorgeschlagene Implementierung kann etwas Speicher verschwenden, wenn Instanz-Structs eine geringere Ausrichtung als alignof(max_align_t) benötigen. Auch die Behandlung von Ausrichtungen macht die Berechnung langsamer, als sie sein könnte, wenn wir uns auf die korrekt für den Subtyp ausgerichtete base->tp_basicsize verlassen könnten.

Mit anderen Worten, die vorgeschlagene Implementierung konzentriert sich auf Sicherheit und Benutzerfreundlichkeit und tauscht dafür Platz und Zeit. Wenn sich herausstellt, dass dies ein Problem ist, kann die Implementierung angepasst werden, ohne die API zu brechen.

• Der Offset zum typspezifischen Puffer kann gespeichert werden, sodass PyObject_GetTypeData effektiv (char *)obj + cls->ht_typedataoffset ist, was die Leistung auf Kosten eines zusätzlichen Zeigers in der Klasse potenziell verbessert.
• Dann kann ein neues PyType_Slot die gewünschte Ausrichtung angeben, um den Speicherbedarf für Instanzen zu reduzieren.

Andere Layouts für variable Typen

Ein Flag wie Py_TPFLAGS_ITEMS_AT_END könnte hinzugefügt werden, um das in Erweiterung von variablen Objekten beschriebene „tuple-ähnliche“ Layout anzuzeigen, und alle von dieser PEP vorgeschlagenen Mechanismen könnten angepasst werden, um es zu unterstützen. Andere Layouts könnten ebenfalls hinzugefügt werden. Es scheint jedoch nur sehr wenig praktischen Nutzen zu geben, daher ist es nur eine theoretische Möglichkeit.