Other Topics
============

Wrapping Enums using ABI v12
----------------------------

When using ABI v12 SIP wraps C/C++ named enums using a dedicated Python type
and implements behaviour that mimics the C/C++ behaviour regarding the
visibility of the enum's members.  In other words, an enum's members have the
same visibility as the enum itself.  For example::

    class MyClass
    {
    public:
        enum MyEnum
        {
            Member
        }
    }

In Python the ``Member`` member is referenced as ``MyClass.Member``.  This
behaviour makes it easier to translate C/C++ code to Python.

In more recent times C++11 has introduced scoped enums and Python has
introduced the :mod:`enum` module.  In both cases a member is only visible in
the scope of the enum.  In other words, the ``Member`` member is referenced as
``MyClass.MyEnum.Member``.

SIP generates bindings for C++11 scoped enums and implements them as Python
:class:`enum.Enum` objects.

A disadvantage of the above is that the Python programmer needs to know the
nature of the C/C++ enum in order to access its members.  In order to avoid
this, SIP makes the members of traditional C/C++ enums visible from the scope
of the enum as well.

It is recommended that Python code should always specify the enum scope when
referencing an enum member.

When using ABI v13 SIP uses the :mod:`enum` module to wrap all C/C++ named
enums.

When using ABI v14 the behaviour can be configured using the
:directive:`%SipModuleConfiguration` directive.


.. _ref-object-ownership:

Ownership of Objects
--------------------

When a C++ instance is wrapped a corresponding Python object is created.  The
Python object behaves as you would expect in regard to garbage collection - it
is garbage collected when its reference count reaches zero.  What then happens
to the corresponding C++ instance?  The obvious answer might be that the
instance's destructor is called.  However the library API may say that when the
instance is passed to a particular function, the library takes ownership of the
instance, i.e. responsibility for calling the instance's destructor is
transferred from the SIP generated module to the library.

Ownership of an instance may also be associated with another instance.  The
implication being that the owned instance will automatically be destroyed if
the owning instance is destroyed.  SIP keeps track of these relationships to
ensure that Python's cyclic garbage collector can detect and break any
reference cycles between the owning and owned instances.  The association is
implemented as the owning instance taking a reference to the owned instance.

The :aanno:`TransferThis`, :aanno:`Transfer` and :aanno:`TransferBack` argument
annotations are used to specify where, and it what direction, transfers of
ownership happen.  It is very important that these are specified correctly to
avoid crashes (where both Python and C++ call the destructor) and memory leaks
(where neither Python and C++ call the destructor).

This applies equally to C structures where the structure is returned to the
heap using the :c:func:`free` function.

See also :c:func:`sipTransferTo` and :c:func:`sipTransferBack`.


.. _ref-types-metatypes:

Types and Meta-types
--------------------

Every Python object (with the exception of the :class:`object` object itself)
has a meta-type and at least one super-type.  By default an object's meta-type
is the meta-type of its first super-type.

SIP implements two super-types, :class:`sip.simplewrapper` and
:class:`sip.wrapper`, and a meta-type, :class:`sip.wrappertype`.

:class:`sip.simplewrapper` is the super-type of :class:`sip.wrapper`.  The
super-type of :class:`sip.simplewrapper` is :class:`object`.

:class:`sip.wrappertype` is the meta-type of both :class:`sip.simplewrapper`
and :class:`sip.wrapper`.  The super-type of :class:`sip.wrappertype` is
:class:`type`.

:class:`sip.wrapper` supports the concept of object ownership described in
:ref:`ref-object-ownership` and, by default, is the super-type of all the types
that SIP generates.

:class:`sip.simplewrapper` does not support the concept of object ownership but
SIP generated types that are sub-classed from it have Python objects that take
less memory.

SIP allows a class's meta-type and super-type to be explicitly specified using
the :canno:`Metatype` and :canno:`Supertype` class annotations.

SIP also allows the default meta-type and super-type to be changed for a module
using the :directive:`%DefaultMetatype` and :directive:`%DefaultSupertype`
directives.  Unlike the default super-type, the default meta-type is inherited
by importing modules.

If you want to use your own meta-type or super-type then they must be
sub-classed from one of the SIP provided types.  Your types must be registered
using :c:func:`sipRegisterPyType`.  This is normally done in code specified
using the :directive:`%InitialisationCode` directive.

.. note::

    It is not possible to define new super-types or meta-types if the limited
    Python API is enabled and ABIs v12 or v13 are targeted.


Support for Python's Buffer Interface
-------------------------------------

SIP supports Python's buffer interface in that whenever C/C++ requires a
``char`` or ``char *`` type then any Python type that supports the buffer
interface (including ordinary Python strings) can be used.


Support for Wide Characters
---------------------------

SIP supports the use of wide characters (i.e. the ``wchar_t`` type).  Python's
C API includes support for converting between ``str`` objects and wide
character strings and arrays.  When converting from a ``str`` object to wide
characters SIP creates the string or array on the heap (using memory allocated
using :c:func:`sipMalloc()`).  This then raises the problem of how this memory
is subsequently freed.

The following describes how SIP handles this memory in the different situations
where this is an issue.

    - When a wide string or array is passed to a function or method then the
      memory is freed (using :c:func:`sipFree()`) after that function or method
      returns.

    - When a wide string or array is returned from a virtual method then SIP
      does not free the memory until the next time the method is called.

    - When an assignment is made to a wide string or array instance variable
      then SIP does not first free the instance's current string or array.


.. _ref-gil:

The Python Global Interpreter Lock (or Free-threading)
------------------------------------------------------

Python's GIL must be acquired (or, in the context of free-threading, a thread
state attached) before calls can be made to the Python API.  It should also be
released (or detached) when a potentially blocking call to C/C++ library is
made in order to allow other Python threads to be executed.  In addition, some
C/C++ libraries may implement their own locking strategies that conflict with
the GIL causing application deadlocks.  SIP provides ways of specifying when
the GIL is released (or thread state detached) and acquired (or attached) to
ensure that locking problems can be avoided.

SIP always ensures that the GIL is acquired (or thread state attached) before
making calls to the Python API.  By default SIP does not release the GIL (or
attached thread state) when making calls to the C/C++ library being wrapped.
The :fanno:`ReleaseGIL` annotation can be used to override this behaviour when
required.

If the ``release-gil`` key is set to ``true`` in the bindings-specific section
of the ``pyproject.toml`` file then (for that set of bindings) then the default
behaviour is changed and SIP releases the GIL (or attached thread state) every
time is makes calls to the C/C++ library being wrapped.  The :fanno:`HoldGIL`
annotation can be used to override this behaviour when required.


.. _ref-subclass-convertors:

Writing :directive:`%ConvertToSubClassCode`
-------------------------------------------

When SIP needs to wrap a C++ class instance it first checks to make sure it
hasn't already done so.  If it has then it just returns a new reference to the
corresponding Python object.  Otherwise it creates a new Python object of the
appropriate type.  In C++ a function may be defined to return an instance of a
certain class, but can often return a sub-class instead.

The :directive:`%ConvertToSubClassCode` directive is used to specify
handwritten code that exploits any available real-time type information (RTTI)
to see if there is a more specific Python type that can be used when wrapping
the C++ instance.  The RTTI may be provided by the compiler or by the C++
instance itself.

The directive is included in the specification of one of the classes that the
handwritten code handles the type conversion for.  It doesn't matter which
one, but a sensible choice would be the one at the root of that class
hierarchy in the module.

.. note::

    In a future version of SIP this use of the directive will be deprecated and
    it will instead be placed outside any class specification.

If a class hierarchy extends over a number of modules then this directive
should be used in each of those modules to handle the part of the hierarchy
defined in that module.  SIP will ensure that the different pieces of code are
called in the right order to determine the most specific Python type to use.

A class has at least one convertor if it or any super-class defines
:directive:`%ConvertToSubClassCode`.  A convertor has a base class.  If a class
that defines :directive:`%ConvertToSubClassCode` does not have a super-class
that defines :directive:`%ConvertToSubClassCode` then that class is the base
class.  Otherwise the base class is that of the right-most super-class that has
a convertor.  In this case the :directive:`%ConvertToSubClassCode` extends all
other convertors with the same base class.

Consider the following class hierarchy::

    A
      \
       B*     C*
         \  /   \
          D      E
        /   \
      F       G*

The classes marked with an asterisk define :directive:`%ConvertToSubClassCode`.

Classes ``A`` to ``F`` are implemented in module ``X``.  Class ``G`` is
implemented in module ``Y``.

We can say the following:

- ``A`` has no convertor, all other classes do.

- The base class of ``B``'s :directive:`%ConvertToSubClassCode` is ``B``.

- The base class of ``C``'s :directive:`%ConvertToSubClassCode` is ``C``.

- ``D`` and ``F`` have two convertors ``B`` and ``C``.

- ``E``'s convertor is ``C``.

- The base class of ``G``'s :directive:`%ConvertToSubClassCode` is ``C``.

- ``B``'s :directive:`%ConvertToSubClassCode` must handle instances of ``B``,
  ``D`` and ``F`` (i.e. those sub-classes of its base class defined in the same
  module).

- ``C``'s :directive:`%ConvertToSubClassCode` must handle instances of ``C``,
  ``D``, ``E`` and ``F``.

- ``G``'s :directive:`%ConvertToSubClassCode` must handle instances of ``G``.

A convertor is invoked when SIP needs to wrap a C++ instance and the type of
that instance is a sub-class of the convertor's base class.  The convertor is
passed a pointer to the instance cast to the base class.  The convertor then,
if possible, casts that pointer to an instance of a sub-class of its original
class.  It also returns a pointer to the corresponding
:ref:`generated type specification <ref-type-specs>`.

It is possible for a convertor to switch to another convertor.  This can avoid
duplication of convertor code where there is multiple inheritance.

When more than one convertor may be invoked they are done so in the order that
reflects the module hierarchy.  When the convertors are defined in the same
module then the order is undefined.  Convertors must be written with this mind.

Given the class hierarchy shown above, lets say that SIP needs to wrap an
instance of known to be of class ``D`` but is actually of class ``F``.  We want
the conversion mechanism to recognise that fact and return a Python object of
type ``F``.  The following steps are taken:

- ``G``'s :directive:`%ConvertToSubClassCode` is invoked and passed the pointer
  to ``D`` cast to ``C``.  This convertor only recognises instances of class
  ``G`` and so returns a value that indicates it was unable to perform a
  conversion.

- SIP will now invoke either ``B``'s :directive:`%ConvertToSubClassCode` or
  ``C``'s :directive:`%ConvertToSubClassCode`.  As they are defined in the same
  module which is chosen is undefined.  Let's assume it is the ``C`` convertor
  that is invoked.

- The convertor recognises that the instance is of class ``D`` (rather than
  ``C`` or ``E``).  It must also determine whether this really is ``D`` or
  whether it is actually ``F``.  Of course ``B``'s
  :directive:`%ConvertToSubClassCode` must also make the same distinction.
  Rather than possibly duplicating the required code in both convertors the
  ``C`` convertor switches to the ``B`` convertor.  It does this by casting the
  pointer it is trying to convert to ``B`` and returns ``B``'s
  :ref:`generated type specification <ref-type-specs>`.
