Purpose

This file describes the implementation of the _ctypes module.

ctypes internals

Structure is the most important (externally visible) part of the _ctypes module.

It consists of the following building blocks:

• StgDictObject, which is a subclass of PyDictObject

• MemoryTypeObject metaclass, subclass of PyTypeObject

• MemoryObject, subclass of object

• CFieldObject

Among other C compatible data types implemented in the _ctypes module, Structure instances store their attributes in a C accessible memory block.

The memory block must have a certain size, combining memory blocks has certain alignment requirement, and so on. (XXX Have to explain the need for the length field)

StgDictObject

StgDictObject works around the problem that it's currently not possible to attach additional C accessible structure members to type objects.

For cases where this is needed, we replace the type's tp_dict member, which is normally a PyDictObject instance, with a StgDictObject instance.

StgInfoObject is a subclass of PyDictObject, but has additional C accessible fields:

        struct {
                int size;
                int align;
                int length;
                PyObject *proto;
        };

These fields hold information about the memory block's requirements.

MemoryTypeObject

MemoryTypeObject is used as the (base) metaclass for Structure and other C data types. The constructor makes sure several requirements are met (a Structure subclass must have a _fields_ attribute, _Pointer and Array subclasses must have a _type_ attribute, and so on). It also analyzes the memory requirements, and replaces the type's tp_dict member by a StgDictObject instance.

There are C api functions to access the StgDictObject of type objects:

      /*
       * Retrieve the size, align, and length fields of the type object's
       * StgDictObject if it has one. Returns 0 on success.
       * If an error cccurrs, -1 is returned and an exception is set.
       */
      int PyType_stginfo(PyTypeObject *self,
                         int *psize,
                         int *palign,
                         int *plength);

      /*
       * Return the proto field of the type's StgDictObject, if there is one.
       * Returns NULL if an error occurrs, but does not set an exception.
       * Returns a borrowed reference.
       */
      PyObject *PyType_spamdictproto(PyObject *self);

MemoryObject

This is the base class for all concrete C data types. It contains the memory block described by the type's StgDictObject.

There are C api functions to access the StgDictObject of the object's type:

      /*
       * Retrieve the size, align, and length fields of the object type's
       * StgDictObject if it has one. Returns 0 on success.
       * If an error cccurrs, -1 is returned and an exception is set.
       */
      int PyObject_stginfo(PyObject *self,
                           int *psize,
                           int *palign,
                           int *plength);

      /*
       * Return the proto field of the object type's StgDictObject,
       * if there is one. Returns NULL if an error occurrs,
       * but does not set an exception.
       * Returns a borrowed reference.
       */
      PyObject *PyObject_spamdictproto(PyObject *self);

CFieldObject

This is a descriptor object: it knows how to convert between C and Python data types and back, and how to store and retrieve the data from the memory block.

When a new subclass of Structure is created (by the metaclass), the constructor populates the new class' tp_dict with CFieldObject instances constructed from the _fields_ attribute.